Error Codes

DocPeel uses standard HTTP status codes plus a machine-readable error.codeyou can branch on safely. Human-readable error.message may change between versions — never match against it.

HTTP statuses

Status	Meaning
200	Success.
400	Validation failed (missing field, wrong format).
401	Missing or invalid API key.
403	Authenticated, but not allowed (insufficient scope or workspace mismatch).
404	Resource not found.
413	File exceeds the 20 MB limit.
429	Rate limit exceeded.
500	Unexpected server error — safe to retry with exponential backoff.
503	Extraction engine temporarily unavailable.

Error codes

Code	Description
`missing_authorization`	No `Authorization` or `x-api-key` header present.
`invalid_api_key`	The provided key was not recognised or has been revoked.
`insufficient_scope`	Key is valid but does not have the required scope.
`missing_file`	The `file` form field was not present.
`invalid_file`	File format is unsupported.
`file_too_large`	File exceeds 20 MB.
`insufficient_credits`	Workspace has no remaining credits.
`not_found`	The requested resource does not exist or is in another workspace.
`extraction_failed`	The extraction engine could not parse the document. Credits are refunded automatically.
`rate_limited`	Too many requests for the current plan's per-minute or per-day quota. Inspect `Retry-After` and the `X-RateLimit-*` headers, or upgrade your plan.
`internal_error`	Server-side error. Retry with backoff and contact support if it persists.

Retry policy

Idempotent retries are safe for 5xx and 429. Use exponential backoff with jitter (e.g. 1 s, 2 s, 4 s, 8 s, …). Do not retry 4xx errors — fix the request first.