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