Developer docs

Errors

Errors are JSON with one error object. code is stable and meant for programs; message is for people and may change. field names the parameter at fault, when there is one.

400 Bad Request

{
  "error": {
    "code": "invalid_query",
    "message": "limit must be an integer from 1 to 10000",
    "field": "limit"
  }
}

Status codes

Status	Meaning	What to do
400	The request is malformed.	Fix the parameter in `error.field`; do not retry unchanged.
401	No API key, or a wrong or deleted one.	Check the key; create a new one if it was deleted.
404	The alias group or provider does not exist.	Check the id or slug against the list endpoints.
409	A conflict: the alias group changed while paging, a workspace limit was reached, or the webhook is paused.	For `alias_changed`, start again from the first page; for a limit or a paused webhook, see the code.
429	Too many requests, or too many invitations today.	Wait for `retry-after` seconds, then retry.
500	Our failure.	Retry with exponential backoff; contact support if it persists.

Error codes

The price history API's codes are listed with it: Price history errors. The other endpoints that accept a key add:

Status	Code	When
404	`provider_not_found`	`GET /v1/catalog`: the `provider` slug is unknown or missing. The price history answers an unknown slug in `providers` with `400 invalid_query` instead.

Limits return these (Limits). Only rate_limited can answer an API key; the others come from the web app, signed in, when it creates or saves a webhook, an API key, a workspace or an invitation:

Status	Code	When
429	`rate_limited`	Over a rate limit. Wait `retry-after` seconds.
409	`webhook_limit`	The workspace has 20 webhooks already. Delete one to create another.
409	`api_key_limit`	The workspace has 20 API keys already. Delete one to create another.
400	`invalid_body`	A field of the webhook or key is invalid or over its limit; `error.field` names it. For example more than 50 alias groups on one webhook (`aliases`), more than 200 entries in one filter, or a name over 80 characters.
409	`organization_limit`	You belong to 3 workspaces already, so you cannot create another.
409	`organization_busy`	Another workspace is being created for you at the same moment. Refresh and retry.
429	`invitation_limit`	The workspace sent 20 invitations in the last 24 hours. `retry-after` says when the next one can go out.

Managing webhooks in the app can show these. They come from the signed-in app's own routes, which API keys cannot call (Managing webhooks):

Status	Code	When
400	`invalid_url`	The endpoint URL is not allowed: it is not `https` on port 443, it has credentials or a fragment, or its host is an IP address, a local name or a name that resolves to an address that is not public. See Delivery.
409	`webhook_paused`	The webhook is paused: Send test event and Resend are refused until you choose Resume deliveries.

Handle an unknown code by its HTTP status.