Errors

When a request fails, Korti says what happened and what to do next, in one sentence.

The shape of an error

Every error has the same shape and an HTTP status that matches. type is stable, so write code against it. message is written for people, and may change. param is there when one field caused it.

Response422 Unprocessable Entity

{
  "error": {
    "type": "invalid_value",
    "message": "stamps can be up to 10 on this card. You sent 11.",
    "param": "values.stamps"
  }
}

Error types

Status	Type	When	What to do
400	`invalid_json`	The body isn’t valid JSON.	Check for a missing quote or a trailing comma.
401	`unauthorized`	The key is missing, mistyped or revoked.	Send Authorization: Bearer sk_…, or create a new key.
403	`trial_limit`	All trial passes are used.	Go live in Settings → Live cards: verify your company, add a payment card and set up Apple Wallet.
403	`test_limit`	Test keys have issued 100 passes in the last seven days.	Wait for older test passes to expire, or void ones you no longer need and use a live key for real customers.
403	`apple_not_ready`	A live pass is added to Apple Wallet after the business disconnected its own certificate and has no issuing agreement.	Set up Apple Wallet again in Settings → Apple Wallet.
403	`account_frozen`	Korti has turned off issuing and updates for this business after a reported problem.	Email korti@korti.is.
403	`apple_expired`	Your own Apple certificate has expired.	Renew it in Settings → Apple Wallet.
409	`apple_certificate_gone`	Updating an Apple pass whose certificate is no longer connected.	Issue the customer a new pass.
404	`not_found`	No card, pass or endpoint with that ID in this business.	Check the ID, and that the key belongs to the same business.
409	`card_not_published`	The card is a draft.	Publish it in the dashboard, then retry.
409	`card_full`	A stamp card already has every stamp, or you set stamps to a number below the total on a full card.	Redeem the reward first, or set stamps to 0 to start a new round.
409	`reward_not_ready`	Redeeming a stamp card that isn’t full.	Add the remaining stamps.
409	`renewal_too_soon`	A pass that got a new stamp round or a later validUntil less than 10 minutes ago gets another.	Wait the time the message names, then retry.
409	`pass_voided`	Changing a voided pass.	Issue a new pass.
409	`idempotency_conflict`	An Idempotency-Key reused for a different request.	Use a new key for each new request.
413	`payload_too_large`	The request body is larger than 64 KB.	Send less in one request.
415	`unsupported_media_type`	A body sent without Content-Type: application/json.	Add the header.
422	`payment_card_needed`	The business has no payment card on file and has issued 50 cards or renewals (refills, new stamp rounds, later validity dates). Issuing a card and refilling a klippikort are both billed as a card, and so are the other renewals, but only a refill is refused here.	Add a payment card in Settings → Billing.
422	`payment_overdue`	An invoice is overdue and the business has issued 100 new cards or renewals (refills, new stamp rounds, later validity dates) since it first failed.	Update the payment card in Settings → Billing, or retry the payment. Issuing resumes at once when it goes through.
422	`invalid_request`	A field is missing, misspelt or the wrong type.	param names the field; message says what to send.
422	`invalid_value`	A value breaks the card’s rules, like 11 stamps on a 10-stamp card.	See the card’s variables in GET /v1/cards/{id}.
422	`value_out_of_range`	A points or balance change is over 1,000,000, or the pass would hold more than 1,000,000,000.	Send a smaller delta.
422	`too_many_custom_values`	An update would give a pass more than 20 custom values.	Send only the custom values you want to set.
422	`wrong_card_type`	Points on a stamp card, or a balance on a points card.	Use the endpoint for that kind of card.
422	`insufficient_balance`	Spending more than a gift card holds.	Spend less, or top up first.
429	`rate_limited`	More than 100 requests a minute with one key, or 300 a minute across all the keys of a business.	Wait for Retry-After seconds.
500	`server_error`	Something broke on Korti’s side.	Retry with the same Idempotency-Key.

Which errors to retry

Retry 429 after the Retry-After seconds, and 500 or network errors with a short, growing wait. Send the same Idempotency-Key so a retry never does the work twice.
Don’t retry anything in the 400s without changing something first. The same request will fail the same way.