Qoder CN Series:Errors

The Qoder Cloud Agents API returns all errors using a unified error envelope format. Each error response contains structured information for programmatic handling and troubleshooting.

Error envelope format

All error responses follow this JSON structure:

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<human-readable error description>",
    "param": "<name of the parameter that triggered the error (optional)>"
  }
}

Field descriptions

Field	Type	Required	Description
type	string	Yes	Always "error"
request_id	string	Yes	Request correlation ID from x-request-id; a server-generated UUID if not provided
error.type	string	Yes	Error type identifier
error.message	string	Yes	Human-readable error description
error.param	string	No	Name of the request parameter that triggered the error

Error types overview

HTTP status code	error.type	Description
400	invalid_request_error	Invalid or missing request parameters
401	authentication_error	Authentication failed; token is invalid or missing
403	permission_error	Authentication succeeded but access to the target resource is denied
404	not_found_error	The target resource does not exist
409	conflict_error	Resource state conflict (for example, duplicate creation)
500	api_error	Internal server error

Error type details

400 — invalid_request_error

The request format or parameters are invalid.

Common triggers:

• Missing a required field (for example, name)

• Incorrect field value type (for example, a string expected but a number provided)

• Request body exceeds the 4 MB size limit

• Malformed JSON

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

# Trigger example: missing the name field
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'

401 — authentication_error

Authentication failed.

Common triggers:

• No Authorization header provided

• Malformed PAT format

• Expired or revoked PAT

• Using x-api-key instead of a Bearer Token

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

# Trigger example: using an invalid token
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

Authentication succeeded but you lack the required permissions.

Common triggers:

• The PAT has no access to the target Agent (it belongs to another user or organization)

• The PAT permission scope does not cover the current operation

• Attempting to operate on an archived and locked resource

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}

# Trigger example: accessing another user's Agent
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents/agent_other_user_123" \
  -H "Authorization: Bearer $QODER_PAT"

404 — not_found_error

The target resource does not exist.

Common triggers:

• Agent/Session/Environment ID does not exist

• Resource has been deleted

• Typo in the URL path

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

# Trigger example: querying a non-existent Agent
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents/agent_nonexistent_123" \
  -H "Authorization: Bearer $QODER_PAT"

409 — conflict_error

Resource state conflict; the operation cannot be executed.

Common triggers:

• Repeated request using the same idempotency key but a different request body

• Attempting to continue operating on an already-terminated Session

• Duplicate creation of a uniquely-named resource

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}

500 — api_error

Internal server error.

Common triggers:

• Service temporarily unavailable

• Internal component exception

• Database connection timeout

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again later."
  }
}

Error handling best practices

1. Parse error.type for programmatic error handling rather than relying on HTTP status codes

2. Log request_id and error.message for troubleshooting

3. If present, check error.param to quickly locate the problematic field

4. Do not retry 4xx errors (unless you have modified the request parameters)

5. Use backoff retry for 5xx errors (maximum 3 retries)

# Example request with error handling
response=$(curl -s -w "\n%{http_code}" \
  "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT")

# Extract HTTP status code
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  # Extract error type
  error_type=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['error']['type'])")
  echo "API error: $error_type"
fi