Errors, status codes and safe retries

The error body

Every error — on either ring — returns a JSON object with a machine-readable code, a human message, and where relevant a details array pinpointing the offending field. Branch on code, not on the message text, which may be reworded. The HTTP status tells you the family; the code tells you the specific fault. See the full tables for the public ring and partner ring.

Which errors to retry

Status	Meaning	Retry?
400 / 422	Bad or invalid request	No — fix the request
401 / 403	Auth / scope problem	No — fix the credential
404	Unknown resource	No
409	Conflict (e.g. duplicate)	No — reconcile first
429	Rate limited	Yes — after RateLimit-Reset
5xx	Server error	Yes — exponential back-off

Retrying safely

A retry is only safe if a replayed write cannot double-act. On mutating partner calls, send an idempotency key: the server records the first result against the key and returns that same result for any replay, so a network-timeout retry of POST /applications never opens two cases. Combine idempotency keys with exponential back-off plus jitter, and cap your total attempts — see the back-off recipe.

Frequently asked questions

Should I retry a 422?

No. A 422 means the request itself is invalid — a bad amount, a missing field, an out-of-range term. Retrying the identical request just fails again. Fix the request using the details array and resubmit.

Is it safe to retry a POST that timed out?

Only if you sent an idempotency key. With a key, the server returns the original result on replay instead of acting twice, so a timed-out application submission cannot become two applications. Without a key, a blind retry can duplicate the action.