REST API Errors
Errors use one JSON shape:
| Status | Common error values | Meaning |
|---|---|---|
| 400 | invalid_request | JSON or a required field is invalid |
| 401 | unauthorized | The API key or session Bearer token is missing, invalid, expired, or revoked |
| 402 | subscription_required, ledger limit codes | The account cannot start this paid operation |
| 403 | insufficient_scope, forbidden | The key lacks a scope or cannot access the resource |
| 404 | not_found | The account-owned resource or linked repository was not found |
| 409 | conflict | The resource cannot accept the operation in its current state |
| 413 | payload_too_large | Declared preview artifact sizes exceed upload limits |
| 429 | rate_limited | Wait for Retry-After before retrying |
| 500 | internal_error | The request failed unexpectedly |
Treat the error value as the stable programmatic field. Log message for
operators. Retry 429 responses after the supplied delay. Retry 500 responses
with bounded exponential backoff. Do not retry 400, 401, 402, 403, 404, or 409
until the request, credentials, account funding, or repository setup changes.
