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

# 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:

```json theme={null}
{
  "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

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

```bash theme={null}
# 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

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

```bash theme={null}
# 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

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

```bash theme={null}
# 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

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

```bash theme={null}
# 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

```json theme={null}
{
  "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

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

<Note>For 500 errors, retry with exponential backoff (for example, 1s → 2s → 4s).</Note>

## 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).

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Overview" icon="rocket" href="/cloud-agents/overview">
    How Qoder Cloud Agents fits together.
  </Card>
</CardGroup>