Skip to main content
Every error response uses the same structure. 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 reused with different parameters
connectionConnection 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

CodeHTTPDescription
api_error500Platform error
timeout500Platform timed out
endpoint_deprecated400Endpoint is deprecated and pending removal
CodeHTTPDescription
idempotency_error409Same key, different parameters
CodeHTTPDescription
timeout504Could not connect in time
blocked503Blocked by antibot
CodeHTTPDescription
rate_limit_exceeded429Too many requests
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
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
auth_header_invalid400Malformed Authorization header
environment_invalid400Key environment does not match request
connection_not_found404Connection does not exist
connection_closed400Connection is not open
connection_terminated409Credentials were deleted
connection_in_use429Connection is running another task
connection_not_ready429Connection has not finished authenticating
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
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
CodeHTTPDescription
mfa_timeout408MFA prompt expired
interaction_timeout408Interaction window expired
CodeHTTPDescription
task_failed500Task execution failed
task_result_unknown500Completed but result could not be determined
timeout408Execution timed out
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...",
  "connection_id": "conn_a1b2c3d4...",
  "agent_id": "agt_a1b2c3d4...",
  "source_id": "src_a1b2c3d4...",
  "runtime_ms": 12453,
  "output": null,
  "errors": [
    {
      "type": "source",
      "code": "source_blocked",
      "message": "Source blocked the connection."
    }
  ],
  "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.