Error handling

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

Error structure

{
  "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.

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.

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.

{
  "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.

Get Started

Guides

Development

Platform

Integrations

Migration Guides

Error structure

Handling errors

Error types

Success rate

Error codes by type

api

idempotency

session

rate_limit

source

request

auth

interaction

task

storage

organization

Errors on resource objects

Request IDs

​Error structure

​Handling errors

​Error types

​Success rate

​Error codes by type

​api

​idempotency

​session

​rate_limit

​source

​request

​auth

​interaction

​task

​storage

​organization

​Errors on resource objects

​Request IDs

Error structure

Handling errors

Error types

Success rate

Error codes by type

api

idempotency

session

rate_limit

source

request

auth

interaction

task

storage

organization

Errors on resource objects

Request IDs