Stable error contract

Errors and limits

Branch on the machine-readable error code and HTTP status, never on human text.

{ "error": "insufficient_api_key_scope" }

Project quotas

Account API keys share 600 read requests/minute and 120 write requests/minute per key. Reseller API defaults to 1,200 reads/minute and 300 writes/minute shared by the reseller tenant; staff can raise an individual tenant up to 60,000 read RPM and 12,000 write RPM. Every response returns RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 also returns Retry-After.

401 Unauthorized

Missing, expired, revoked, malformed, or security-invalidated key.

403 Forbidden

Insufficient scope or source IP outside the key allowlist.

404 Not Found

Missing and cross-tenant object references deliberately share the same response.

409 Conflict

Lifecycle conflict, idempotency mismatch, or an uncertain provider result still in progress.

428 Precondition Required

A mutation requires an Idempotency-Key or another explicit precondition.

429 Too Many Requests

Use bounded retries with jitter and respect the returned retry policy.

5xx Server error

Retry reads safely. Retry mutations only with the exact same idempotency key and payload.