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.
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 === "mfa_timeout") {
promptUserForNewMfaCode();
}
if (error.type === "rate_limit") {
retryWithBackoff();
}
Error types
| Type | When it occurs |
|---|
api | Deck platform failure |
idempotency | Idempotency key error |
session | Session could not be established |
rate_limit | Too many requests |
source | External source failure or unavailability |
request | Invalid input, missing fields, or unsupported action |
auth | Credential or authentication method failure |
interaction | MFA or interaction timeout |
task | Task execution failure |
storage | File storage or extraction failure |
Error codes by type
api
| Code | HTTP | Description |
|---|
api_error | 500 | Platform error |
timeout | 500 | Platform timed out |
endpoint_deprecated | 400 | Endpoint is deprecated and pending removal |
idempotency
| Code | HTTP | Description |
|---|
idempotency_error | 409 | Same key, different parameters |
idempotency_key_error | 400 | Idempotency key must be at most 256 characters |
session
| Code | HTTP | Description |
|---|
timeout | 504 | Session could not start in time |
rate_limit
| Code | HTTP | Description |
|---|
rate_limit_exceeded | 429 | Too many requests |
session_limit_exceeded | 429 | Agent sandbox limit exceeded |
source
| Code | HTTP | Description |
|---|
source_error | 503 | External source failure |
source_invalid | 400 | Invalid source ID |
source_not_found | 404 | Source does not exist |
source_not_available | 503 | Source is down or unreachable |
source_blocked | 403 | Source is on a blocklist |
request
These are the most common errors. They indicate a problem with your request.
| Code | HTTP | Description |
|---|
input_invalid | 400 | Validation failed |
input_type_invalid | 400 | Wrong type |
input_format_invalid | 400 | Wrong format |
input_missing | 400 | Required field missing |
input_too_long | 400 | Exceeds max length |
input_too_short | 400 | Below min length |
input_duplicate | 409 | Must be unique |
query_param_invalid | 400 | Unsupported query parameter |
cursor_invalid | 400 | Pagination cursor is invalid or expired |
resource_not_found | 404 | Resource does not exist |
resource_not_ready | 409 | Resource is not in a usable state |
api_key_invalid | 401 | Invalid API key |
token_invalid | 401 | Invalid token |
auth_header_invalid | 400 | Malformed Authorization header |
environment_invalid | 400 | Key environment does not match request |
credential_not_found | 404 | Credential does not exist |
credential_invalid | 400 | Credential was rejected by the source |
action_not_supported | 400 | Not supported for this source |
feature_not_available | 403 | Not available on your plan |
quota_exceeded | 403 | Plan quota exceeded |
task_not_found | 404 | Task does not exist |
task_not_supported | 400 | Task not supported for this source |
interaction_required | 429 | Blocked until pending interaction is resolved |
interaction_input_invalid | 400 | Submitted interaction data is invalid |
interaction_not_required | 400 | No interaction was requested |
interaction_not_found | 404 | Interaction does not exist |
mfa_input_invalid | 400 | MFA code is wrong |
storage_not_found | 404 | Storage item does not exist |
auth
| Code | HTTP | Description |
|---|
auth_method_not_supported | 400 | Auth method not supported for this source |
auth_not_supported | 400 | Source does not require authentication |
auth_required | 401 | Authentication is required |
auth_invalid | 401 | Credentials are wrong |
password_reset_required | 400 | Source is forcing a password reset |
account_locked | 400 | Account is locked at the source |
proxy_invalid | 400 | Custom proxy configuration is invalid |
interaction
| Code | HTTP | Description |
|---|
mfa_timeout | 408 | MFA prompt expired |
interaction_timeout | 408 | Interaction window expired |
task
| Code | HTTP | Description |
|---|
blocked | 503 | Blocked by antibot |
task_failed | 500 | Task execution failed |
task_result_unknown | 500 | Completed but result could not be determined |
timeout | 408 | Execution timed out |
storage
| Code | HTTP | Description |
|---|
timeout | 408 | Storage request timed out |
extraction_failed | 500 | Document extraction failed |
extraction_timeout | 408 | Extraction 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.
