Skip to main content
Conventions

Errors

Unified error envelope, error types, and troubleshooting for the Qoder Cloud Agents API.

The Qoder Cloud Agents API returns errors in a consistent envelope. Each error response carries structured fields suitable for programmatic handling and debugging.

Error envelope

All error responses follow this JSON structure: 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<human-readable description>",
    "param": "<offending parameter name (optional)>"
  }
}

Field descriptions

FieldTypeRequiredDescription
typestringYesAlways "error"
request_idstringYesRequest correlation ID from x-request-id or a generated UUID
error.typestringYesError type identifier
error.messagestringYesHuman-readable error description
error.paramstringNoName of the request parameter that caused the error

Error types

HTTP statuserror.typeDescription
400invalid_request_errorInvalid or missing request parameters
401authentication_errorAuthentication failed; token missing or invalid
403permission_errorAuthenticated but not authorized for the resource
404not_found_errorTarget resource does not exist
409conflict_errorResource state conflict (for example, duplicate creation)
500api_errorInternal server error
503feature_not_availableA Beta feature is not enabled for this account
503api_errorA required external service is temporarily unavailable; retry

Error type details

400 — invalid_request_error

The request format or parameters are invalid. Common triggers:
  • Missing required field (for example, name)
  • Field type mismatch (such as a number where a string is expected)
  • Body exceeds the 4 MB limit
  • Malformed JSON
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

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

401 — authentication_error

Authentication failed. Common triggers:
  • Missing Authorization header
  • Malformed PAT or SAT
  • PAT expired or revoked, or SAT expired
  • x-api-key used instead of a bearer token
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

# Example trigger: invalid token
curl -s https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

Authenticated but not authorized. Common triggers:
  • The PAT or SAT does not have access to the target Agent
  • The PAT or SAT scopes do not cover this 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."
  }
}

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

404 — not_found_error

The target resource does not exist. Common triggers:
  • Agent, Session, or Environment ID does not exist
  • The resource is no longer available
  • URL path typo
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

# Example trigger: nonexistent Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_nonexistent_123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

409 — conflict_error

Resource state conflict prevents the operation. Common triggers:
  • Same idempotency key reused with a different request body
  • Operating on a terminated Session
  • Creating a duplicate 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 failure
  • 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."
  }
}
For 500 errors, retry with exponential backoff (for example, 1s → 2s → 4s).

503 — feature_not_available

The feature is in Beta and the current account is not eligible to use it. Common triggers:
  • The request carries a Beta's x-qoder-beta identifier, but the Beta is disabled or the account is not on its allowlist.
  • The matching Beta runtime policy is not configured on the service.
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "feature_not_available",
    "message": "oss_bucket beta is currently disabled."
  }
}
When a required external service is temporarily unavailable (for example, validating an OSS bucket or assuming a role through STS while saving an Environment), the API can also return 503 api_error. Retry those with backoff.

Error handling best practices

  1. Branch on error.type rather than the HTTP status code.
  2. Log request_id and error.message for diagnostics.
  3. Inspect error.param when present to locate the offending field.
  4. Do not retry 4xx errors unless the request was modified.
  5. Retry 5xx errors with exponential backoff (up to 3 attempts).
# 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")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

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

Next steps

Overview

How Qoder Cloud Agents fits together.