> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Every error returns a consistent structure with a deterministic type, code, and request ID.

Errors are always returned as an array, regardless of how many occurred, so your error handling logic only needs one code path.

## Error structure

```json theme={null}
{
  "errors": [
    {
      "type": "request",
      "code": "input_missing",
      "field": "name",
      "message": "`name` is required and cannot be empty."
    }
  ],
  "request_id": "req_a1b2c3d4..."
}
```

| Field | Description |
| - | - |
| `type` | Error category. Determines the class of failure. |
| `code` | Machine-readable error code. Use this for programmatic handling. |
| `field` | The input field that caused the error, when applicable. |
| `message` | Human-readable explanation. Do not rely on this for logic. |
| `request_id` | Unique identifier for the request. Send this to Deck support when troubleshooting. |

## Handling errors

Use `type` and `code` for branching logic. The `message` field is for logging and display only. It may change.

```javascript theme={null}
if (error.type === "auth" && error.code === "auth_invalid") {
  promptUserToReAuthenticate();
}

if (error.type === "interaction" && error.code === "interaction_timeout") {
  promptUserForNewMfaCode();
}

if (error.type === "rate_limit") {
  retryWithBackoff();
}
```

## Error types

Errors are grouped as **Deck Errors**, **Request Errors**, or **Source Errors**. Only Deck Errors count against a task's [success rate](#success-rate).

| Type | When it occurs | Group |
| - | - | - |
| `api` | Deck platform failure | Deck Error |
| `idempotency` | Idempotency key error | Request Error |
| `session` | Session could not be established | Deck Error |
| `rate_limit` | Too many requests | Request Error |
| `source` | External source failure or unavailability | Source Error |
| `request` | Invalid input, missing fields, or unsupported action | Request Error |
| `auth` | Credential or authentication method failure | Request Error |
| `interaction` | MFA or interaction timeout, or an interaction on a run with interactions suppressed | Request Error |
| `task` | Task execution failure | Deck Error |
| `storage` | File storage or extraction failure | Deck Error |
| `organization` | Plan, billing, or entitlement state blocks the request. Retrying will not help; the customer must upgrade, take billing action, or wait for the next billing cycle. | Request Error |

## Success rate

Success rate is the share of task runs that completed successfully over a given time period. Only Deck Errors count against it.

* Runs that succeed count as successes.
* Runs that fail with a Deck Error count as failures.
* Runs that fail with a Request Error or Source Error are excluded from the calculation, since it was impossible for Deck to complete the task.

```
success_rate = successes / (successes + deck_error_failures)
```

## Error codes by type

### api

| Code | Description |
| - | - |
| `api_error` | Platform error |
| `timeout` | Platform timed out |
| `endpoint_deprecated` | Endpoint is deprecated and pending removal |

### idempotency

| Code | Description |
| - | - |
| `idempotency_error` | Same key, different parameters |
| `idempotency_key_error` | Idempotency key must be at most 256 characters |

### session

| Code | Description |
| - | - |
| `timeout` | Session could not start in time |

### rate\_limit

| Code | Description |
| - | - |
| `rate_limit_exceeded` | Too many requests |
| `session_limit_exceeded` | Agent sandbox limit exceeded |

### source

| Code | Description |
| - | - |
| `source_error` | External source failure |
| `source_not_available` | Source is down or unreachable |
| `source_blocked` | Source is on a blocklist |

### request

These are the most common errors. They indicate a problem with your request.

| Code | Description |
| - | - |
| `input_invalid` | Validation failed |
| `input_type_invalid` | Wrong type |
| `input_format_invalid` | Wrong format |
| `input_missing` | Required field missing |
| `input_too_long` | Exceeds max length |
| `input_too_short` | Below min length |
| `input_duplicate` | Must be unique |
| `query_param_invalid` | Unsupported query parameter |
| `invalid_field_value` | A submitted field value is not valid (e.g. `settings.timeout_seconds` is not a positive integer) |
| `timeout_exceeds_plan_max` | The requested task timeout exceeds the maximum allowed by your plan |
| `cursor_invalid` | Pagination cursor is invalid or expired |
| `resource_not_found` | Resource does not exist |
| `resource_not_ready` | Resource is not in a usable state |
| `api_key_invalid` | Invalid API key |
| `token_invalid` | Invalid token |
| `credential_not_found` | Credential does not exist |
| `source_not_found` | Source does not exist |
| `action_not_supported` | Not supported for this source |
| `task_not_found` | Task does not exist |
| `task_not_supported` | Task not supported for this source |
| `interaction_required` | Blocked until pending interaction is resolved |
| `interaction_input_invalid` | Submitted interaction data is invalid |
| `interaction_not_required` | No interaction was requested |
| `interaction_not_found` | Interaction does not exist |
| `storage_not_found` | Storage item does not exist |
| `attachment_invalid` | Input file failed its security scan. Returned asynchronously on the task run. |

### auth

| Code | Description |
| - | - |
| `auth_method_not_supported` | Auth method not supported for this source |
| `auth_not_supported` | Source does not require authentication |
| `auth_required` | Authentication is required |
| `auth_invalid` | Credentials are wrong |
| `password_reset_required` | Source is forcing a password reset |
| `account_locked` | Account is locked at the source |

### interaction

| Code | Description |
| - | - |
| `interaction_timeout` | Interaction window expired |
| `interaction_suppressed` | Run needed an interaction, but interactions were suppressed for the run |

### task

| Code | Description |
| - | - |
| `blocked` | Blocked by antibot |
| `extraction_failed` | Document extraction failed for one or more captured files |
| `task_failed` | Task execution failed |
| `task_result_unknown` | Completed but result could not be determined |
| `timeout` | Execution timed out |

### storage

| Code | Description |
| - | - |
| `timeout` | Storage request timed out |
| `extraction_timeout` | Extraction timed out |

### organization

| Code | Description |
| - | - |
| `quota_exceeded` | Plan quota exceeded |
| `task_length_exceeded` | Task exceeded the maximum length allowed by the plan |
| `feature_not_available` | Feature is not available on the current plan |
| `plan_inactive` | Subscription is past due or canceled |
| `balance_insufficient` | Deck balance is insufficient to complete the request; add to your balance and retry |

## Errors on resource objects

When a task run fails, the `errors` array is populated on the run object itself. This is the same structure as API-level errors.

```json theme={null}
{
  "id": "trun_a1b2c3d4...",
  "object": "task_run",
  "status": "failed",
  "result": "failure",
  "task_id": "task_a1b2c3d4...",
  "credential_id": "cred_a1b2c3d4...",
  "session_id": "sess_x9y8z7...",
  "agent_id": "agt_a1b2c3d4...",
  "source_id": "src_a1b2c3d4...",
  "runtime_ms": 12453,
  "output": null,
  "errors": [
    {
      "type": "source",
      "code": "source_blocked",
      "message": "Source blocked the credential."
    }
  ],
  "interaction": null,
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:31:15Z",
  "request_id": "req_a1b2c3d4..."
}
```

## Request IDs

Every response includes a `request_id`. When contacting Deck support, include this value to speed up troubleshooting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.