Errors and retries

HTTP status codes

Status	What to check
`401`	Key missing, invalid, expired or revoked. Obtain a valid key.
`403`	A required scope or operation-specific access rule is not satisfied.
`404`	Resource missing, deleted or outside the key's profile, for operations using this boundary response.
`422`	Request validation or a documented domain constraint failed. Correct the input.
`429`	A request limit was exceeded. Respect the `Retry-After` response header.
`500`	A technical failure occurred. Check the actual result before retrying a write.

The operation's reference is authoritative. For example, availability may return 403 for an employee outside the profile, while other resource lookups return 404. Do not infer one resource's response from another.

Error bodies

Authentication and conflict errors use errors.code and errors.message. Validation formats vary by operation. Some expose errors.fields, some expose field errors directly and others return domain-specific fields. Do not require a global data envelope or assume every validation response has errors.fields.

Use HTTP status and documented fields for decisions. X-Locale changes message text without changing scope names or JSON keys.

Limits

The default business limit is 200 requests per 60 seconds per presented key, including invalid keys. Without a key, this limit uses the source IP. A separate IP limit defaults to 4000 per 60 seconds. Deployment settings may change the IP limit. Do not automatically retry authentication or validation failures.

Retrying writes

Do not blindly retry a write after a timeout. Its effects may already exist. Read back the affected resource and follow the endpoint's documented duplicate handling. Selected creation operations accept checkSum and timeCache; these are operation-specific, time-limited duplicate protection rather than a global idempotency guarantee. The protection window is at most 300 seconds and does not provide a permanent response history. A repeated request may execute again after it expires. Do not invent an Idempotency-Key header for operations that do not support it.

For transient read failures, use bounded retries with increasing delays and respect Retry-After when present. Report failures without including API keys or private response payloads.