Errors & status codes

Errors return a non-2xx HTTP status with the standard error envelope:

{ "status":"error", "message":"Invalid client credentials.", "code":"unauthorized" }

HTTP status codes

Code	Meaning	What to do
200	Success.	Read `data`.
400	Bad request — a field is missing or invalid.	Fix the payload; don't retry unchanged.
401	Unauthorized — token missing or expired.	Get a new token and retry once.
403	Forbidden — bad credentials or not allowed.	Check credentials / app permissions.
404	Not found — e.g. unknown charge_ref or payer.	Verify the reference.
409	Conflict — e.g. duplicate non-idempotent action.	Use an `idem` key.
429	Too many requests — rate limited.	Back off per `Retry-After` and retry.
500	Internal error.	Safe to retry idempotent calls with backoff.

code	Typical HTTP	Meaning
invalid_request	400	A parameter is missing or malformed.
unauthorized	401	Token missing, invalid or expired.
forbidden	403	Authenticated but not permitted.
not_found	404	The referenced object doesn't exist.
limit_exceeded	400	A control-profile limit (per-txn/daily/balance) was hit.
rate_limited	429	Too many requests in the window.
server_error	500	Unexpected error on our side.

Branch on the HTTP status first, then read message for the human reason and code for a stable machine value.
Retry only idempotent calls (those with an idem key) on 401/429/500/timeouts.
Log message; never show raw API errors to end customers.