Errors

Error envelope

API errors return a standard JSON envelope with a human-readable detail and a stable, machine-readable code:

1
{
2
  "detail": "Insufficient balance",
3
  "code": "insufficient_balance"
4
}

Branch your error handling on code (stable), not detail (human-facing text that may change).

A few errors add machine-readable fields next to detail and code — for example a price_mismatch carries the real price:

1
{
2
  "detail": "Price mismatch: the current price for this order is 26.50",
3
  "code": "price_mismatch",
4
  "actual_price": 26.50,
5
  "submitted_price": 24.00
6
}

Read those extras only for the code that documents them, and tolerate unknown keys — new ones can be added without a breaking change.

detail is a plain human-readable fallback and never carries internal or infrastructure information. A 5xx therefore reports only that the service is unavailable — the underlying cause stays in our logs, not in your response body.

Status codes

Examples

1
{ "detail": "Item is not available", "code": "validation_error" }

1
{ "detail": "Insufficient balance", "code": "insufficient_balance" }

1
{
2
  "detail": "Price mismatch: the current price for this order is 26.50",
3
  "code": "price_mismatch",
4
  "actual_price": 26.50,
5
  "submitted_price": 24.00
6
}

1
{ "detail": "Authentication credentials were not provided.", "code": "not_authenticated" }

1
{ "detail": "Not found.", "code": "not_found" }

Create-time errors vs. async failures

There are two kinds of “failure”, and they surface in different places:

• Create-time (HTTP) errors — the request is rejected and nothing is charged. These come back as a 4xx/5xx with the error envelope when you call POST /v1/orders. Example: an item out of stock at create time returns 400 validation_error (“Item is not available”).

• Async failures (terminal status) — the order was accepted (201, status: "pending") and your balance was charged, but fulfillment later fails or only partially succeeds. This is not an HTTP error. The order settles on a terminal status of failed (with an error code — see Order error codes — and a full refund_amount) or partial (with a refund_amount for the undelivered units). You learn this from your webhook or GET /v1/orders/{id}.

Order error codes

When an order settles as failed (or partial), its error field carries a stable, machine-readable code and error_message carries a human-readable description. Branch on error (stable); show or log error_message (text that may change). Both appear on GET /v1/orders/{id} and in the webhook event.

Some of these conditions are usually caught up front at create time and returned as a 4xx instead (see Status codes); when they are only detected during fulfillment, they surface here as the order’s error.

Retrying safely

Always send a unique merchant_order_id on POST /v1/orders. It is unique per account, so a retry (after a timeout or 5xx) that reuses the same value won’t place a duplicate order — a duplicate is rejected with a 400 validation_error.