Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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",
  "error": {
    "type": "<error_type>",
    "message": "<human-readable description>",
    "param": "<offending parameter name (optional)>",
    "feature": "<required feature identifier (501 only)>",
    "available_from": "<beta identifier that exposes the feature (501 only)>"
  }
}

​
Field descriptions

FieldTypeRequiredDescription
typestringYesAlways "error"
error.typestringYesError type identifier
error.messagestringYesHuman-readable error description
error.paramstringNoName of the request parameter that caused the error
error.featurestringNoFeature that needs activation (501 only)
error.available_fromstringNoBeta identifier exposing the feature (501 only)

​
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
501feature_not_availableFeature not enabled; activation via Beta header required

​
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 32 MB limit
  • Malformed JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

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

​
401 — authentication_error

Authentication failed. Common triggers:
  • Missing Authorization header
  • Malformed PAT
  • PAT expired or revoked
  • x-api-key used instead of a bearer token
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

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

​
403 — permission_error

Authenticated but not authorized. Common triggers:
  • The PAT does not have access to the target Agent (different user or organization)
  • The PAT scopes do not cover this operation
  • Attempting to operate on an archived and locked resource
{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}

# Example trigger: accessing another user's Agent
curl -s https://openapi.qoder.sh/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, or Environment ID does not exist
  • The resource has been deleted
  • URL path typo
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

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

​
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",
  "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",
  "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).

​
501 — feature_not_available

The requested feature is not yet enabled and requires a Beta header. Common triggers:
  • Required Beta feature identifier missing
  • Outdated Beta identifier
{
  "type": "error",
  "error": {
    "type": "feature_not_available",
    "feature": "managed-agents",
    "available_from": "managed-agents-2026-04-01"
  }
}

# Example trigger: missing beta header
curl -s https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT"

​
Error handling best practices

  1. Branch on error.type rather than the HTTP status code.
  2. Log error.message for diagnostics.
  3. Inspect error.param 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://openapi.qoder.sh/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