Core concepts / Errors

Errors

Errors use the same envelope as success, so you parse one shape everywhere. On failure, status is "error", data is null, and error carries a stable numeric code, a human message, and optional field details.

Error envelope

{
  "status": "error",
  "data": null,
  "error": {
    "code": 5001,
    "message": "Insufficient credits. Please top up your account.",
    "details": []
  }
}

Code families branch on the number, not the message

Range	Family	Meaning	HTTP
1xxx	Authentication	Missing, invalid, or revoked API key; IP not allowed.	401
2xxx	Validation	The request was malformed, a required field is missing or a value is out of range.	400
3xxx	Resource	The thing you asked for does not exist (an unknown job id, for example).	404
4xxx	System	Something failed on our side. Safe to retry.	500
5xxx	Business	The request is understood but not allowed right now, most often insufficient credits.	402
6xxx	Integration	A downstream or third-party step failed.	502

◈

Match on error.code, never on error.message. The code is stable across releases; the message may be reworded or localized. For example, always treat 5001 as out-of-credits rather than string-matching the text.