Errors use one shape:

{ "error": { "code": "stale_timestamp", "message": "…", "details": [{ "path": "installId", "message": "Invalid UUID" }] } }

Switch on code, never on message.

Signing errors (401)#

`code`	Meaning	What the app should do
`missing_signature`	A signing header is missing	Fix the client
`bad_timestamp`	Not whole seconds (milliseconds land here)	Fix the client
`stale_timestamp`	More than 5 minutes from server time	Retry with backoff; log a clock warning in debug builds
`invalid_key`	Unknown or revoked key, or the app was deleted	Stop sending; log loudly in debug builds
`bad_signature`	Wrong secret, or the body changed after signing	Fix the client

Only stale_timestamp can succeed on retry.

Other errors#

Status	`code`	What the app should do
400	`validation_failed`	A field is wrong; `details` lists each one. Fix the client.
400	`platform_mismatch`	The body's `platform` doesn't match the key. Use the right platform's key.
413	`fst_err_ctp_body_too_large`	The body is over 64 KB.
5xx, network error	—	Retry on the next launch.