Errors

Use status code + error body together to drive retry and user messaging behavior.

Common status codes

Status	Meaning	Recommended client behavior
400	Invalid request payload	Fix request construction, do not retry unchanged
401	Missing/invalid API key	Refresh credentials/configuration
403	Key not authorized for resource	Check endpoint entitlement/key scope
404	Resource not found	Validate identifier/path
429	Rate limit reached	Read Retry-After, pause sending on that key, then retry gradually
500	Internal server error	Retry with exponential backoff
503	Temporary service issue	Retry with exponential backoff and jitter

Client-side best practices

• Log status code, endpoint, and correlation metadata.
• Treat 4xx as client-actionable unless documented otherwise.
• Treat 5xx as transient and retry with bounded attempts.
• For 429, also log X-RateLimit-* headers and error.details.retryAfter when present.