Errors

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.

Errors5 min

View as Markdown

Getting startedSee the common error envelope in the queued job flow.Rate limitsUnderstand 429 rate_limit_exceeded and retry behavior.

Section

Error Envelope

Rate limit response

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry later.",
    "type": "rate_limit_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Section

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

Section

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.

Code Samples

Rate limit response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry later.",
    "type": "rate_limit_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}