API error codes
Every error is application/problem+json. Branch on code, never on title or detail. Codes are only ever added; treat one you do not know by its status.
authentication_required 401
Authentication required
The request has no Authorization header. Every v1 request needs `Authorization: Bearer <your API key>`. A dashboard session is not accepted.
invalid_api_key 401
Invalid API key
The bearer is not a key we know: a typo, a truncated copy, or a key whose business has changed hands. Repeated failures from one address are rate limited.
api_key_revoked 401
API key revoked
The key was revoked on the API & Webhooks page. It stops working on the next request. Create a new key.
api_key_expired 401
API key expired
The key passed the expiry date set when it was created. Create a new key.
test_key_not_supported 401
Test keys not accepted
No longer sent: test keys (fdl_test_…) work on your sandbox since the sandbox shipped. Kept because a code is never removed.
not_supported_yet 401
Credential not supported yet
OAuth access tokens are not accepted yet. Use an API key.
plan_required 403
Plan required
API access is part of the Enterprise plan, and the account that owns this key is not on it. The key is kept and works again after an upgrade.
key_mode_mismatch 403
Key mode mismatch
This key cannot be used here: a test key works only on your sandbox (demo data), and a live key never does.
insufficient_scope 403
Insufficient scope
The key does not have the scope this request needs. `detail` names it.
forbidden 403
Forbidden
The key may not do this for its business.
not_found 404
Not found
Nothing with this id exists in the key's business. Ids from another business are answered the same way.
invalid_cursor 400
Invalid cursor
The `cursor` was not issued for this list, this business and these filters, or it was changed. Start again without `cursor`, then use `next_cursor` exactly as returned.
invalid_parameter 400
Invalid parameter
A query parameter is out of range or malformed. `param` names it. `limit` is 1–100.
validation_failed 422
Validation failed
The request body was refused. `errors` lists each field: `param`, `code` and `message`.
idempotency_key_required 400
Idempotency key required
Every write needs an `Idempotency-Key` header: 1 to 255 visible ASCII characters, unique per write (a UUID is ideal). Retrying a write with the same key never does it twice.
idempotency_key_reused 422
Idempotency key reused
This `Idempotency-Key` was already used, by the same key, for a different request (another route or another body). Use a new key for a new write. Keys are remembered for 24 hours.
idempotency_in_progress 409
Request in progress
A request with this `Idempotency-Key` is still being processed. Retry after `Retry-After` seconds to get its answer. If the first request never answered (a timeout), check the result before writing again with a new key.
customer_exists 409
Customer already enrolled
This email is already enrolled on this pass. `detail` gives the customer id; read it with GET /customers/{id}. Nothing was created and nothing was sent.
customer_limit_reached 403
Customer limit reached
The plan's customer allowance for this business is used (a sandbox, for a test key, holds up to 500 customers). Nothing was created.
card_not_active 409
Card not active
The card is not active (deleted, or replaced), so nothing can be recorded on it. `detail` gives its status.
insufficient_balance 409
Not enough balance
More than the card holds: points on a loyalty card (POST /scans), or money or sessions on a gift card (POST /gift_cards/{id}/payments, where `balance` says what is left). Nothing was taken.
no_reward_available 409
No reward to redeem
The card has no reward ready to redeem. Nothing was recorded.
scan_refused 409
Scan refused
The scan was refused by the card's rules (for example a points action on a visits card). `detail` says why. Nothing was recorded.
currency_mismatch 422
Currency mismatch
The payment's `currency` is not the gift card's. `detail` names the card's currency. Nothing was taken: amounts are never converted.
gift_card_not_claimed 409
Gift card not claimed yet
The recipient has not opened their gift card yet, so it cannot pay. It can once they have (its `status` is then `active`). Nothing was taken.
gift_card_cancelled 409
Gift card cancelled
The gift card was cancelled and cannot pay. Nothing was taken.
gift_card_depleted 409
Gift card used up
The gift card's balance is 0 (`status` `depleted`), and nothing ever adds to it again. Nothing was taken.
pass_required 409
Pass required
The business needs a pass before it can do this (a gift card takes its look from the business's pass).
broadcast_not_in_plan 403
Messages not in the plan
The account's plan includes no messages to customers this month.
broadcast_quota_reached 403
Message quota reached
This month's messages to customers are used (scheduled ones count in the month they go out). Nothing was sent.
confirmation_token_invalid 400
Invalid confirmation token
The `confirmation_token` is not one we issued. Ask for a new preview with POST /broadcasts.
confirmation_token_expired 410
Confirmation token expired
A confirmation token lives 10 minutes. Ask for a new preview with POST /broadcasts. Nothing was sent.
confirmation_token_used 409
Confirmation token used
This confirmation token has already been used: its message was sent (or is being sent). A token sends once.
confirmation_payload_changed 422
Message changed since the preview
The message confirmed is not the one previewed (its pass, title, body, targeting or schedule differ). Ask for a new preview of the message you want to send. Nothing was sent.
confirmation_audience_changed 409
Audience grew since the preview
More customers would receive the message now than the preview showed (for example, people joined since). Ask for a new preview: nothing was sent.
confirmation_principal_mismatch 403
Token issued to someone else
This confirmation token was issued to another API key or assistant. Only the one that asked for the preview may confirm it.
confirmation_business_mismatch 403
Token issued for another business
This confirmation token was issued for another business.
recent_visit 409
Visit just recorded
This card had a visit less than 15 minutes ago (`last_visit_at` says when). Nothing was recorded. If it really is a new visit, send the request again with `"confirm_repeat": true`.
broadcast_already_sent 409
Message already sent
The message has been sent, or is being sent right now (or was sent at once, never scheduled), so it can no longer be cancelled. Nothing changed.
rate_limited 429
Rate limited
Too many requests in the window. Wait `Retry-After` seconds. `RateLimit-Policy` and `RateLimit` say which window and what remains.
internal_error 500
Internal error
Something failed on our side. Quote the `request_id` if you contact us.