Errors

Every error uses the same envelope:


{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this call"
  },
  "request_id": "req_7ed41a20-822f-4221-a674-cb84ebc74077"
}

Branch on error.code, not the message — messages may improve over time; codes are stable and only ever added to. Include the request_id when contacting support.

Error codes

Code	HTTP	Meaning
`invalid_request`	400	Malformed input — missing required field, bad JSON, unfetchable URL
`unsupported_format`	400	The file isn’t a PDF or plain text (DOCX not yet supported)
`invalid_key`	401	Missing, unknown, or revoked access key
`insufficient_credits`	402	Balance too low — the call was not charged
`not_found`	404	No such resource
`idempotency_conflict`	409	Idempotency key reused with a different payload
`parse_failed`	422	The document couldn’t be structured (e.g. an image-only scan)
`missing_candidate`	422	`/match` or `/score/requirements` got no usable candidate input
`missing_role`	422	`/match` or `/score/requirements` got no usable role input
`rate_limited`	429	Too many requests — back off and retry
`internal_error`	500	Our fault. Retry once; if it persists, report the `request_id`

Retry guidance

429 and 500: safe to retry with exponential backoff — failed calls were refunded.
4xx (everything else): don’t retry unchanged; the request itself needs fixing.
Long documents can take tens of seconds on /parse/* and /match — set client timeouts to at least 120 seconds.