Errors

Every error — validation, authentication, business rule, or unexpected — returns the same shape. You never have to branch on the response format.

{
  "error": {
    "code": "INSUFFICIENT_SCOPES",
    "message": "This API key does not have the required permissions.",
    "details": [
      { "field": "scopes", "issue": "Missing required scope: payouts:write" }
    ],
    "request_id": "req_01HX..."
  }
}

Field	Description
`code`	Stable, machine-readable identifier. Branch on this.
`message`	Human-readable summary. Safe to log; do not parse.
`details`	Field-level problems, each with a `field` and an `issue`. May be empty.
`request_id`	Echoes your `X-Request-Id`. Quote it in support requests.

Branch on code, never on message. Messages are wording and may be reworded at any time; codes are part of the contract and only change with a version bump.

Status codes

Status	Meaning	What to do
`400`	Validation or business-rule failure	Fix the request. Retrying unchanged fails identically.
`401`	Missing or invalid API key	Check the key. See Authentication.
`403`	Valid key, insufficient scope, or KYB not approved	Fix configuration. Never retry.
`404`	Not found, or not yours	Check the ID. Another account’s records read as `404`.
`409`	Conflict — duplicate in flight, or invalid state	Back off and retry.
`422`	Semantically invalid — expired quote, bad destination	Re-derive the input.
`429`	Rate limited	Back off. `details` carries the retry delay.
`500`	Unexpected failure on our side	Retry with the same idempotency key. Quote the `request_id`.
`503`	An upstream service is unreachable	Transient. Retry with backoff.

Retry matrix

Retryable	Not retryable
`409`, `429`, `500`, `503`	`400`, `401`, `403`, `404`, `422`

Retry the left column with backoff, reusing the same Idempotency-Key. The right column needs the request or your configuration to change first — a retry loop on a 422 is just a slower failure.

Every code

Authentication and authorisation

Code	Status
`MISSING_API_KEY`	`401`
`INVALID_API_KEY`	`401`
`API_KEY_INACTIVE`	`401`
`API_KEY_REVOKED`	`401`
`API_KEY_EXPIRED`	`401`
`TENANT_INACTIVE`	`401`
`INSUFFICIENT_SCOPES`	`403`
`COMPLIANCE_NOT_APPROVED`	`403`
`RATE_LIMIT_EXCEEDED`	`429`

Idempotency

Code	Status	Meaning
`MISSING_IDEMPOTENCY_KEY`	`400`	No `Idempotency-Key` on a write
`REQUEST_IN_PROGRESS`	`409`	The original request is still running

Payouts

Code	Status	Meaning
`PAYOUT_NOT_FOUND`	`404`	No such payout for your account
`REFUND_DESTINATION_REQUIRED`	`422`	No refund destination for the settlement currency
`UNSUPPORTED_CORRIDOR`	`422`	No corridor for that currency pair
`SETTLEMENT_BELOW_MINIMUM`	`422`	Settlement amount under the corridor floor
`PAYOUT_SANCTIONS_BLOCKED`	`403`	Blocked by sanctions screening
`VELOCITY_LIMIT_EXCEEDED`	`422`	Account or destination velocity limit hit

Rates and quotes

Code	Status	Meaning
`QUOTE_NOT_FOUND`	`404`	No such quote
`QUOTE_EXPIRED`	`422`	Past its TTL — lock a fresh one
`QUOTE_NOT_ACCEPTABLE`	`409`	Already accepted or used
`RATE_UNAVAILABLE`	`503`	Could not price the corridor right now

Beneficiary lookup

Code	Status	Meaning
`INVALID_DESTINATION_ACCOUNT`	`422`	No account with those details
`DESTINATION_ACCOUNT_INACTIVE`	`422`	Account exists but cannot receive
`DESTINATION_TYPE_NOT_ENQUIRABLE`	`400`	Crypto has no directory or name
`ACCOUNT_NAME_MISMATCH`	`422`	Supplied name does not match the institution’s

Settlement and refunds

Code	Status	Meaning
`PAYMENT_INSTRUCTION_NOT_FOUND`	`404`	Not generated yet, or no active one
`INFLOW_NOT_FOUND`	`404`	No such settlement
`OUTFLOW_NOT_FOUND`	`404`	No such dispatch attempt
`REFUND_NOT_FOUND`	`404`	No such refund
`UNSUPPORTED_REFUND_DESTINATION`	`400`	Refunds in that currency are not supported
`BANK_ACCOUNT_VERIFICATION_FAILED`	`422`	Name enquiry failed — destination not saved
`SETTLEMENT_TARGET_UNAVAILABLE`	`503`	Could not provision a settlement target

Webhooks

Code	Status	Meaning
`WEBHOOK_NOT_CONFIGURED`	`422`	No webhook URL set for the account
`WEBHOOK_URL_INVALID`	`400`	Not a valid URL, or not HTTPS

Platform

Code	Status	Meaning
`LIQUIDITY_ENGINE_UNAVAILABLE`	`503`	Upstream pricing or payout engine unreachable
`INTERNAL_ERROR`	`500`	Unexpected failure. Never leaks internals.

Not every code you will see is an API error code. DISPATCH_ERROR and similar values appear as failure_code on an outflow or a refund record — they describe why an attempt failed downstream, and never come back as the code of an HTTP error response.

PAYMENT_INSTRUCTION_NOT_FOUND is the one 404 that is routinely not an error. Instructions are generated asynchronously, so for a few seconds after creating a payout there genuinely is not one yet. Wait for payout.pending_payment rather than treating it as a failure.

Tracing a request

Send an X-Request-Id and it is echoed in the response and into every log line and error we record. Generate one per attempt and log it next to your own record.

curl -X POST "$SPENDIN_BASE_URL/v1/payouts" \
  -H "X-API-Key: $SPENDIN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If you do not send one, request_id is reported as unknown — which makes a support request considerably harder to answer.

Use a fresh X-Request-Id per attempt and a stable Idempotency-Key across attempts of the same operation. They serve opposite purposes: one identifies this HTTP call, the other identifies the business operation behind it.

Handling errors well

const response = await fetch(url, options);

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'REQUEST_IN_PROGRESS':
    case 'RATE_LIMIT_EXCEEDED':
    case 'RATE_UNAVAILABLE':
    case 'LIQUIDITY_ENGINE_UNAVAILABLE':
      return retryWithBackoff();                 // same idempotency key

    case 'QUOTE_EXPIRED':
      return lockFreshQuoteAndRetry();

    case 'REFUND_DESTINATION_REQUIRED':
    case 'COMPLIANCE_NOT_APPROVED':
    case 'INSUFFICIENT_SCOPES':
      // Configuration, not transport. Retrying will never help.
      throw new ConfigurationError(error.code, error.message);

    case 'INVALID_DESTINATION_ACCOUNT':
      return askUserToCorrectBeneficiary(error.details);

    default:
      logger.error({ code: error.code, request_id: error.request_id });
      throw new SpendinError(error);
  }
}

Log code and request_id on every failure. Those two fields are what turn a support conversation into a lookup.

Getting started

Core concepts

Sending money

Webhooks

Launch

Status codes

Retry matrix

Every code

Authentication and authorisation

Idempotency

Payouts

Rates and quotes

Beneficiary lookup

Settlement and refunds

Webhooks

Platform

Tracing a request

Handling errors well

​Status codes

​Retry matrix

​Every code

​Authentication and authorisation

​Idempotency

​Payouts

​Rates and quotes

​Beneficiary lookup

​Settlement and refunds

​Webhooks

​Platform

​Tracing a request

​Handling errors well

Status codes

Retry matrix

Every code

Authentication and authorisation

Idempotency

Payouts

Rates and quotes

Beneficiary lookup

Settlement and refunds

Webhooks

Platform

Tracing a request

Handling errors well