Errors and retries
Status codes
| Code | Meaning | Retry? |
|---|---|---|
200 | Success. The body is the operation's reply object. | — |
400 | The request body failed validation. | No — fix the call. |
401 | Missing, unknown or mismatched credentials. | No — fix the credentials. |
429 | Over the rate limit for this credential. | Yes, after backing off. |
501 | The operation's contract is published but its implementation has not shipped. | No — watch the phase. |
5xx | A fault on our side. | Yes, with backoff. |
Retry policy
Retry 429 and 5xx with exponential backoff and jitter — start around one second, cap at a minute, give up after a handful of attempts and surface the failure rather than looping forever. Do not retry 400, 401 or 501: none of them becomes a different answer on a second attempt, and a tight retry loop on 401 is the fastest way to get a credential rate-limited as well.
Reads are safe to repeat
Every operation published today is a read, so a retry cannot double-apply anything. When write operations arrive they are idempotent and audit-logged with client attribution, so the same rule will continue to hold.
501 is not an error in your integration
An operation answering 501 has a real, final contract — its fields, types and enum values are committed — and no implementation behind it yet. Build against it if you like; just do not treat the 501 as a transient fault. The alternative, returning an empty result, would be a factual claim that nothing matched, and an integration is entitled to act on that.
Do not parse messages
Branch on the status code and on documented fields. Human-readable messages are for humans, and they change without notice — which is not a breaking change, because nothing promised them.