Every non-200 response is JSON with an errormessage. None of the codes below ever leave you double-charged — a request either isn't charged at all, or is charged and then refunded if it fails after the fact.
| Code | When | Credit |
|---|---|---|
| 400 Bad Request | An invalid or malformed post_id on GET /v1/comments/tree, or any invalid id inside an ids= batch list on GET /v1/posts or GET /v1/comments (one bad id fails the whole call). | No — refunded |
| 401 Unauthorized | The x-api-key / Authorization: Bearer header is missing, or the key is unknown or revoked. | No |
| 402 Payment Required | Credit balance is 0. The response body includes a top-up link. | No |
| 429 Too Many Requests | Either your key's own rate limit (2 req/s sustained, burst 10) or the shared global upstream reserve. A Retry-After header (seconds) is always included; an x-ratelimit-scope: global header distinguishes the shared-pool case from your own per-key limit. | No |
| 502 Bad Gateway | The credit was charged, then the upstream Reddit/Arctic Shift call failed. | No — refunded automatically |
One related gotcha that isn't an error at all: GET /v1/users/{name} for a username with no matching Reddit account still returns a normal 200 with data.user: null — and is still charged 1 credit, since the lookup made a real upstream call either way.