Skip to main content
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..."
}
FieldDescription
typeError category. Determines the class of failure.
codeMachine-readable error code. Use this for programmatic handling.
fieldThe input field that caused the error, when applicable.
messageHuman-readable explanation. Do not rely on this for logic.
request_idUnique 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 === "mfa_timeout") {
  promptUserForNewMfaCode();
}

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

​
Error types

TypeWhen it occurs
apiDeck platform failure
idempotencyIdempotency key error
sessionSession could not be established
rate_limitToo many requests
sourceExternal source failure or unavailability
requestInvalid input, missing fields, or unsupported action
authCredential or authentication method failure
interactionMFA or interaction timeout
taskTask execution failure
storageFile storage or extraction failure

​
Error codes by type

​
api

CodeHTTPDescription
api_error500Platform error
timeout500Platform timed out
endpoint_deprecated400Endpoint is deprecated and pending removal

​
idempotency

CodeHTTPDescription
idempotency_error409Same key, different parameters
idempotency_key_error400Idempotency key must be at most 256 characters

​
session

CodeHTTPDescription
timeout504Session could not start in time

​
rate_limit

CodeHTTPDescription
rate_limit_exceeded429Too many requests
session_limit_exceeded429Agent sandbox limit exceeded

​
source

CodeHTTPDescription
source_error503External source failure
source_invalid400Invalid source ID
source_not_found404Source does not exist
source_not_available503Source is down or unreachable
source_blocked403Source is on a blocklist

​
request

These are the most common errors. They indicate a problem with your request.
CodeHTTPDescription
input_invalid400Validation failed
input_type_invalid400Wrong type
input_format_invalid400Wrong format
input_missing400Required field missing
input_too_long400Exceeds max length
input_too_short400Below min length
input_duplicate409Must be unique
query_param_invalid400Unsupported query parameter
cursor_invalid400Pagination cursor is invalid or expired
resource_not_found404Resource does not exist
resource_not_ready409Resource is not in a usable state
api_key_invalid401Invalid API key
token_invalid401Invalid token
auth_header_invalid400Malformed Authorization header
environment_invalid400Key environment does not match request
credential_not_found404Credential does not exist
credential_deleted409Credential was permanently deleted
credential_invalid400Credential was rejected by the source
action_not_supported400Not supported for this source
feature_not_available403Not available on your plan
quota_exceeded403Plan quota exceeded
task_not_found404Task does not exist
task_not_supported400Task not supported for this source
interaction_required429Blocked until pending interaction is resolved
interaction_input_invalid400Submitted interaction data is invalid
interaction_not_required400No interaction was requested
interaction_not_found404Interaction does not exist
mfa_input_invalid400MFA code is wrong
storage_not_found404Storage item does not exist

​
auth

CodeHTTPDescription
auth_method_not_supported400Auth method not supported for this source
auth_not_supported400Source does not require authentication
auth_required401Authentication is required
auth_invalid401Credentials are wrong
password_reset_required400Source is forcing a password reset
account_locked400Account is locked at the source
proxy_invalid400Custom proxy configuration is invalid

​
interaction

CodeHTTPDescription
mfa_timeout408MFA prompt expired
interaction_timeout408Interaction window expired

​
task

CodeHTTPDescription
blocked503Blocked by antibot
task_failed500Task execution failed
task_result_unknown500Completed but result could not be determined
timeout408Execution timed out

​
storage

CodeHTTPDescription
timeout408Storage request timed out
extraction_failed500Document extraction failed
extraction_timeout408Extraction timed out

​
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...",
  "workflow_id": null,
  "runtime_ms": 12453,
  "output": null,
  "errors": [
    {
      "type": "source",
      "code": "source_blocked",
      "message": "Source blocked the credential."
    }
  ],
  "interaction": null,
  "canceled_at": 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.