Errors

Errors use standard HTTP status codes and return a JSON body with an error object and a requestId:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Field \"Member name\" is required."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}

string

The category of error. See the table below.

string

A stable, machine-readable code, such as missing_idempotency_key. Only some errors have one.

string

A readable explanation. Don’t match on it, because the wording can change.

array

Returned when a template definition is invalid. Lists each problem and where it is.

string

Identifies the request. Include it when you contact support.

Status codes

Status	Type	Meaning
`200`, `201`		Success.
`400`	`invalid_request_error`	The request is invalid, for example an unknown field or a missing required value.
`401`		The API key is missing or invalid. The body carries the code `invalid_api_key`.
`403`	`authorization_error`	The key can’t do this.
`404`	`not_found_error`	The resource doesn’t exist in this key’s organization or environment.
`409`	`conflict_error` or `idempotency_error`	The request conflicts with the current state, such as voiding a pass twice or a reused idempotency key.
`413`	`invalid_request_error`	The upload is too large.
`422`	`api_error`	The request is valid but can’t be done yet, usually because a live certificate or issuer isn’t set up.
`429`	`rate_limit_error`	Too many requests. Wait and retry.
`500`	`api_error`	Something went wrong on our side. Retry with the same idempotency key.

Error codes

Code	Status	Meaning
`invalid_api_key`	`401`	The key is missing, malformed, unknown or revoked.
`missing_idempotency_key`	`400`	A `POST`, `PATCH` or `DELETE` was sent without an `Idempotency-Key`.
`idempotency_conflict`	`409`	The idempotency key was used with a different body.
`idempotency_in_flight`	`409`	The first request with this idempotency key is still running. Wait and retry.

Debugging

Every API request is listed in the dashboard under Developers → Request logs, with its status and response.

Node.js SDK errors

The SDK exposes typed error classes, including TapAceAuthError, TapAceNotFoundError, TapAceConflictError, TapAceIdempotencyError and TapAceRateLimitError. API errors expose status, code and requestId when available. The SDK retries network failures, timeouts, 5xx, 429 and idempotency conflicts classified as in_flight, while attempts remain. Other 409 conflicts are not automatically retried. A timeout does not prove a mutation failed; keep its original stable key when retrying. See SDK errors and retries.

Getting started

Basics

Guides

Node.js SDK

API keys

Passes

Loyalty cards

Notifications

Templates

Wallet signing

Deployments

Assets

Status codes

Error codes

Debugging

Node.js SDK errors

​Status codes

​Error codes

​Debugging

​Node.js SDK errors

Status codes

Error codes

Debugging

Node.js SDK errors