Errors

Every failure carries a machine-readable code. Branch on the code, never on the message, messages are written for humans and may be reworded.

Error shape

{
  "success": false,
  "code": "EVENT_NOT_FOUND",
  "message": "Event not found."
}

Authentication

Code	Status	Do this
MISSING_CREDENTIALS	401	Send both `x-blend-key` and `x-blend-secret`.
INVALID_CREDENTIALS	401	The key is unknown or the secret does not match. Do not retry, it will not start working.
IP_NOT_ALLOWED	403	Send Blend your servers’ egress IPs to add to the allowlist.
SCOPE_DENIED	403	Your key lacks the scope this endpoint needs. Ask Blend to widen it.

Catalog

Code	Status	Do this
EVENT_NOT_FOUND	404	The event does not exist, or is not in your catalog. These are deliberately indistinguishable. Remove it from your UI.
EVENT_CANCELLED	403	The organiser cancelled it. Stop offering it.
EVENT_NOT_AVAILABLE	403	Embargoed, not on sale yet. It may become available later.

Sessions

Code	Status	Do this
INVALID_BUYER_NAME	400	Required, 200 characters or fewer.
INVALID_BUYER_EMAIL	400	Required, must be a valid address, 200 characters or fewer.
INVALID_BUYER_PHONE	400	Optional, 32 characters or fewer when sent.

Inventory and checkout

All of these arrive before the buyer is charged. None of them require a refund.

Code	Status	Do this
TICKET_SOLD_OUT	409	That ticket type is gone. Refresh the event and let the buyer choose again.
EVENT_SOLD_OUT	409	Nothing left on the event.
QUANTITY_EXCEEDS_CAPACITY	409	Fewer remain than requested. Offer the remaining number.
TICKET_QUANTITY_EXCEEDS_CAPACITY	409	As above, for one ticket type.
SEAT_CONFLICT	409	Somebody took the seat first. Return the buyer to the seat map.
hold_expired	409	Returned as `reason`. The hold timed out; take a fresh one.

Idempotency

Code	Status	Do this
duplicate: true	200	Not an error. You replayed a key you already used; the original order is returned. Treat it as success.
KEY_CONFLICT	409	That key was used for a different request. Generate a new key per buyer action.
DUPLICATE_IN_PROGRESS	409	The first request is still running. Wait and poll status rather than retrying immediately.

Confirmation, the ones that involve money

Read this table before you go live

These are the only errors that can occur after you have charged a buyer. Getting the response right is the difference between a clean integration and a support queue.

Code	Status	Do this
INVALID_REQUEST	400	A field is missing or malformed. Nothing was charged on Blend’s side.
SIGNING_KEY_NOT_CONFIGURED	401	Blend has no signing key for your channel. Contact Blend, do not retry.
INVALID_SIGNATURE	401	Almost always the amount was not formatted to two decimals. Sign `42.50`, not `42.5`.
NOT_FOUND	404	That order is not yours. Check the order id you stored.
NOT_PARTNER_REMIT	403	Your channel is not configured to settle this way. Contact Blend.
AMOUNT_MISMATCH	409	You charged a different amount than the order. The response carries `serverTotal`. Refund and re-quote.
CONFIRM_FAILED	409	Carries `refundRequired: true`. Refund the buyer. No ticket was issued and none will be.
ACCRUAL_FAILED_RETRY	503	Transient. Retry. Confirm is idempotent, so retrying cannot double-issue.

When you are not sure what happened

Never assume, and never issue a refund on a timeout alone. A request that timed out may still have succeeded. Ask:

Check the truth

curl -X POST https://api.blendapp.ai/api/v1/channel/orders/status \
  -H "x-blend-key: ck_live_xxxxxxxxxxxxxxxx" \
  -H "x-blend-secret: cs_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"6a9b1c.e42"}'

The answer is paid, pending or failed. That is the authoritative state, and it is safe to ask as often as you need to within the rate limit.

Confirming & settlementThe full confirm contract.Rate limitsWhat each key is allowed.Testing & go-liveRehearse these paths before launch.

Warming up the decks…