Errors

Every failure returns the same envelope, whatever went wrong.

Error envelope

{"error":{"code":"forbidden","message":"This key cannot access this endpoint."}}

Branch on code. The message is written for a human reading a log and may be reworded; the code will not change under you.

The codes

Code	Status	When	Retry?
`bad_request`	400	A parameter is malformed: a bad cursor, a non-integer `limit` or `since`, a `q` outside 2 to 120 characters, or `q` sent anywhere but `/search`.	No. Fix the request.
`unauthorized`	401	No `Authorization` header, not a Bearer token, not key-shaped, unknown, revoked, or expired.	No. Check the key.
`forbidden`	403	The key authenticated, but the plan or the key does not carry the scope this endpoint needs.	No. Add the scope or change plan.
`suspended`	403	The account is suspended, the trial ended, or the subscription lapsed.	No. Settle billing in the console.
`not_found`	404	No story, newsroom, person or brief for that identifier and language.	No.
`rate_limited`	429	More requests this minute than the plan allows.	Yes, after `Retry-After` seconds.
`quota_exceeded`	429	The monthly request quota is used up.	Not until the UTC month rolls over or the plan changes.
`internal`	500	An unexpected failure while authenticating the key.	Yes, once, then report the request id.
`unavailable`	503	A dependency is down or a handler failed.	Yes, with exponential backoff and jitter.

Include X-Request-Id from the failing response, the path, and the UTC time. That is enough to find the request. Write to support@itsbaba.com.