# Error Codes

DocuShell returns structured JSON errors with stable codes and request IDs so integrations can distinguish validation problems, auth failures, rate limits, and transient capacity issues.

Source: https://docs.docushell.com/error-codes
Category: Errors

## Related

- [Getting started](/getting-started.md#error-envelope): See the common error envelope in the queued job flow.
- [Rate limits](/rate-limits.md): Understand `429 rate_limit_exceeded` and retry behavior.
- [Troubleshooting](/troubleshooting.md): Match a failure code to the fix that clears it.

## Error Envelope

Every error on every route uses this shape. `request_id` is also returned in the `x-request-id` header.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

## Common Status Codes

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | invalid_request | Malformed JSON, missing required fields, unsupported file type, invalid URL, or rejected PDF. |
| 401 | invalid_api_key | Missing, revoked, expired, or malformed bearer credential. |
| 403 | api_access_disabled / webhook_access_disabled | Credential is valid, but the current plan state does not allow the API lane or requested webhook fields. |
| 402 | insufficient_credits | The account cannot start the requested job because credits or plan access are insufficient. The error includes hard-limit and upgrade details. |
| 404 | not_found | The requested job, batch, file, artifact, or output does not exist for this authenticated caller. |
| 409 | idempotency_key_reused | The same idempotency key was reused with a different payload. |
| 413 | payload_too_large | The request body or uploaded file exceeds the plan or endpoint limit. |
| 429 | rate_limit_exceeded | The caller exceeded the configured request rate. |
| 500 | internal_error | Unexpected gateway or service failure. |
| 503 | backend_unavailable | A downstream processor or queue was temporarily unavailable. |

## Shared Error Responses

These four are returned by every endpoint. Endpoint pages document only their own additional failures.

### 401 invalid_api_key

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "type": "auth_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

Returned when the bearer token is missing, revoked, expired, or not allowed to use the API lane.

### 409 idempotency_key_reused

```json
{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

Returned when the same Idempotency-Key is reused with a different payload than the original request.

### 403 webhook_access_disabled

```json
{
  "error": {
    "code": "webhook_access_disabled",
    "message": "Webhooks are available on Pro, Growth, and Scale. Starter includes API access without webhooks.",
    "type": "billing_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

Returned when a Starter API key submits webhook fields. Pro, Growth, and Scale include webhooks.

### 429 rate_limit_exceeded

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "type": "rate_limit_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

Returned when the API key or caller fingerprint exceeds the configured request rate.

## Recovery Guidance

- Retry `429`, `500`, and `503` failures with backoff; keep the same `Idempotency-Key` only for the exact same submit request.
- Fix `400` failures before retrying. The same invalid file or request shape will be rejected again.
- Resolve `401`, `403`, and `402` in the dashboard before sending more work. DocuShell does not auto-charge overages.
- Log `request_id` from the error body or `x-request-id` header for support and debugging.