Skip to documentationDocumentation
On this page

Response format

Understand JSON envelopes, request IDs, nullable values, and response headers.

The API returns JSON. Successful responses contain data and meta; failures contain error and meta.

Success responses#

json example
{
  "data": [],
  "meta": { "request_id": "00000000-0000-0000-0000-000000000001" }
}

data is an object, array, or keyed map according to the operation. Invoice, payout, address, and refund lists add has_more and next_cursor to meta; see pagination. Balances return all pairs without pagination. An empty list is a successful response with data: [].

Error responses#

json example
{
  "error": {
    "code": "validation_error",
    "message": "request validation failed"
  },
  "meta": { "request_id": "00000000-0000-0000-0000-000000000001" }
}

Branch on error.code and the HTTP status. Messages are for people and can change; do not parse them. error.details, when present, is an array of strings. See errors.

Request IDs and headers#

HeaderMeaning
X-Request-IDServer-generated request identifier, also returned in meta.request_id
Idempotent-Replayed: trueThe stored outcome of a previous accepted request was returned
Idempotency-Key-Released: trueThis attempt was confirmed to leave the supplied key unbound
Retry-AfterWhen present on a retryable response, wait at least the indicated delay

Provide meta.request_id when asking for support. A caller-supplied request ID does not replace the server's identifier. Each HTTP retry gets its own request correlation even when it replays the same business outcome.

Field conventions#

  • Money and exchange rates are decimal strings, never JSON numbers.
  • Currency codes use uppercase; network keys use lowercase.
  • Timestamps use RFC 3339, normally UTC with Z.
  • UUIDs are opaque identifiers. Do not require a particular UUID version or derive business meaning from them.
  • Required and nullable are separate properties. A required nullable field is present with null until its value exists.
  • Omitted optional request fields are different from explicit null; send null only when the schema permits it.
  • Unknown request fields are rejected where the schema disallows additional properties.

Invoice creation does not allocate a payment address or lock a crypto amount. Those response fields remain null before activation; zero is not a substitute for an unavailable value.

Metadata#

metadata accepts at most 50 string-valued entries, each value at most 500 characters. It is a place for your references, not credentials or sensitive customer data. Invoice metadata omitted at creation is returned as an empty object. Response support for metadata differs between resources; check the individual schema.