Guides

Errors

Every error has one shape, a code to act on and a message to show.

When a request can't be done, the answer has an HTTP status for its kind and a body in the same shape every time:

{
  "error": {
    "code": "validation_error",
    "message": "Unknown field \"primaryFields.0.lable\" (did you mean \"label\"?)",
    "field": "primaryFields.0.lable",
    "requestId": "req_8393c117…"
  }
}

code is what to act on in your code. Codes don't change; new ones may be added, so treat one you don't know by its status.
message is written for a person: log it, or show it to whoever can fix the problem. Its wording can change, so never match on it.
field says which part of the request it's about, when there is one, as a path: primaryFields.0.label is the first primary field's label.
requestId identifies the request. Quote it when you ask us about one.

Some errors add details, named on each endpoint's page: missing lists every placeholder without a value, and preview says how many operations are left when a broadcast or template update won't fit.

Statuses

Status	Means	What to do
400	The request is wrong: a field is missing, too long or unknown	Fix it; sending it again won't help
401	No API key, or not a valid one	Check the `Authorization` header
403	The key can't do this, such as change an organization's template	Do it in the dashboard
404	No such pass, template or broadcast in this workspace	Check the id, and the workspace
409	It clashes with the state things are in: a revoked pass, a slug that's taken, an update already running	Look at the state, then decide
413	The image is over 2 MB	Make it smaller
422	Understood, but it can't be done: an unknown issuer or template, nothing to update	Fix the value it names
429	A limit is reached: this month's operations, or too many requests at once	See below
5xx	Something failed on our side	Retry with the same `Idempotency-Key`

Unknown fields are refused

A misspelt field is never ignored: "lable" would otherwise leave the label off every pass without a word. The answer names the field, and suggests the one you probably meant. The same goes for the filters of a broadcast, so a typo can't send a message to every pass.

Limits

Two kinds of limit answer 429, told apart by their code:

This month's operations are used up: usage_limit_exceeded (your plan), workspace_limit_reached (a limit your organization set on this workspace), or platform_usage_limit (the 1,000 test operations). Retrying won't help until the month resets: see Limits and usage.
Too many requests at once: rate_limited, past about 600 requests a minute for one API key. Wait for the number of seconds in the Retry-After header, then send it again.

Retrying

A 5xx, a 429 rate_limited, or a request that never got an answer (a timeout, a dropped connection) is safe to send again, as long as it carries an Idempotency-Key: see Retries and idempotency. Wait a little longer between each try, such as 1, 2, then 4 seconds. Anything else in the 4xx range will fail the same way again until the request changes.