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

Field	Type	Required	Description
type	string	Yes	Always "error"
request_id	string	Yes	Request correlation ID from x-request-id or a generated UUID
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 caused the error

Error types

HTTP status	error.type	Description
400	invalid_request_error	Invalid or missing request parameters
401	authentication_error	Authentication failed; token missing or invalid
403	permission_error	Authenticated but not authorized for the resource
404	not_found_error	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 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/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",
  "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/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",
  "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/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 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/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",
  "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).

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/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.