Errors and limits

Every failed request answers with a 4xx or 5xx status and a JSON body that says what went wrong. This page lists them all, with what to do about each.

The error body#

{
  "error": "Missing permission: passes.create",
  "code": "insufficient_scope"
}

A validation error on PATCH /pass also carries details, the list of every problem found, and receivedData, the body as the API read it.

Status codes#

401 Unauthorized#

The request carried no key, or one that does not match an active key.

POST /pass, GET /pass and the notify and resend endpoints read the key only from X-API-Key. A key sent there as Authorization: Bearer is not read, and the request answers 401.

402 Upgrade required#

The account is authenticated and the key is allowed to make the request, but the account's plan, trial or billing does not cover it. Every 402 carries "code": "upgrade_required". Retrying, or using another key, gives the same answer; the account owner has to change the plan or fix billing in Billing.

{
  "error": "Your free trial has ended.",
  "code": "upgrade_required",
  "reason": "trial_expired"
}

On POST /pass, reason says why no more passes can be issued:

Elsewhere, feature names what the plan does not include, and for an allowance current and limit give the numbers:

See plans for what each plan includes.

403 Forbidden#

The key is real, but this request is beyond it.

To decide between 401 and 403: 401 means "wrong credential", 403 means "right credential, not enough power". The exception is GET /pass, GET /passes and GET /passes/search, which also answer 401 for a pass or template that belongs to another account.

Error codes#

The access badge endpoints put their code in error itself:

Retrying safely#

• Reads (GET) are always safe to retry.
• Field updates with PATCH /pass set values, so sending the same request twice leaves the same result.
• Stamp operations are safe to retry when you send an idempotencyKey. Walletap remembers the last 20 keys on each card.
• Balance operations are not deduplicated: an add sent twice adds twice. Read the pass before retrying, or state the new total with "operation": "set".
• Issuing with POST /pass creates a new pass, and delivers it, every time. If a request timed out, look the pass up with GET /pass by its externalId before you send it again.

For 500, 502 and 504, retry with exponential backoff: wait one second, then two, then four.

Limits#

Next steps#