Errors

Every error response is JSON, every error has a stable error.code, and every code maps to one HTTP status. Branch on error.code in your code; treat error.message as human text only.

Last updated: April 25, 2026 Reading time: 5 min

Error response shape

{
  "error": {
    "code": "invalid_token",
    "message": "Unknown or revoked key",
    "hint": "Check Profile → API & Billing for active keys."
  }
}

code — stable machine identifier. Switch on this.
message — short human-readable explanation. May be reworded between releases.
hint — optional next-step suggestion. Show to the operator if you don't have a better one.

HTTP status codes

Status	Meaning
200	Success.
400	Bad request — malformed query / missing required parameter.
401	Authentication failed — missing, malformed, unknown or revoked key.
402	Subscription inactive — payment failed or you cancelled and the period ended.
403	Forbidden — you're authenticated but your tier doesn't allow this action.
404	Not found — model/bench slug doesn't exist or is hidden.
422	Unprocessable — semantically wrong, e.g. trying to create a 4th key on Pro tier.
429	Rate-limited or quota exceeded.
500	Internal server error. We're alerted; retry with exponential backoff.
503	Maintenance window. Always accompanied by `Retry-After`.

`error.code` reference

Auth errors (401 / 402)

Code	When
missing_token	No `Authorization` header.
invalid_token_format	Token doesn't start with `sb_live_` or has wrong length.
invalid_token	Token doesn't match any key in our database.
revoked	Key was explicitly revoked from the dashboard.
subscription_inactive	Subscription state is `past_due`, `canceled` or `unpaid`. Update your card via Stripe Customer Portal.

Client errors (400 / 404 / 422)

Code	When
bad_request	Malformed query string or missing required parameter (the `message` says which).
invalid_param	Parameter present but value is invalid (e.g. `limit=99999`).
not_found	No row matches the slug/id you requested.
max_keys_reached	You've hit your tier's active-key cap. Revoke or upgrade.

Limit / forbidden (403 / 429)

Code	When
tier_forbidden	Endpoint not available on your tier (e.g. bulk export on Starter).
rate_limited	More requests in the current calendar minute (UTC) than your per-minute ceiling.
quota_exceeded	Monthly quota for this key reached.

Server errors (500 / 503)

Code	When
internal	Something blew up on our side. We're alerted automatically. Retry with backoff.
maintenance	Planned maintenance window. `Retry-After` tells you when to come back.

Stability promise

HTTP status codes: stable within a major version. We will not change a 422 to a 400 between releases.
error.code values: stable. New codes are additive; existing codes are never repurposed. If we deprecate one, you get a six-month Sunset header before removal.
error.message wording: NOT stable. Localisation, clarification and shortening are allowed at any time.

Always switch on the code. Never regex the message.

Previous ← Rate limits & quotas Next Pagination →