API Error Codes

Errors that apply across endpoints: malformed requests, validation failures, rate limits, lock contention, and unexpected server failures. Codes use the GEN_* prefix.

Errors from API key authentication, authorization scopes, and metrics bearer tokens. Codes use the AUTH_* prefix.

Errors when creating, listing, or validating API keys. Codes use the APIKEY_* prefix.

Errors when creating or fetching ledgers. Codes use the LGR_* prefix.

Errors when creating or fetching accounts. Codes use the ACC_* prefix.

Errors for balance lookups, historical snapshots, monitors, and validation. Codes use the BAL_* prefix.

Errors when recording, validating, committing, voiding, or bulk-processing transactions. Codes use the TXN_* prefix.

Errors for identity records and field tokenization. Codes use the IDT_* prefix.

Errors for reconciliation runs, matching rules, and external data uploads. Codes use the RECON_* prefix.

Errors when updating metadata on ledgers, balances, transactions, and other entities. Codes use the META_* prefix.

Errors for transaction hook registration and management. Codes use the HOOK_* prefix.

Errors from queued async processing. Codes use the QUEUE_* prefix.

Errors from search queries and Typesense reindex jobs. Codes use the SRCH_* prefix.

Errors from admin operations such as database backup. Codes use the ADMIN_* prefix.

Request-level failures reject the whole request, i.e. they reject the whole call before any item runs. Per-item failures are returned inside the bulk result.

The response applies the standard transaction error shape with codes such as TXN_BULK_EMPTY or TXN_BULK_LIMIT_EXCEEDED.

{
  "error": "transactions cannot be empty",
  "error_detail": {
    "code": "TXN_BULK_EMPTY",
    "message": "transactions cannot be empty"
  }
}

Bulk commit expects a transactions array. Bulk void expects transaction_ids. Sending the wrong shape returns TXN_BULK_EMPTY because unrecognized fields are dropped.

Valid requests return HTTP 200 with succeeded, failed, and results. Branch on results[].code, not the HTTP status. Per-item codes are specific to bulk processing and are not part of the TXN_* catalog.

{
  "succeeded": 1,
  "failed": 2,
  "results": [
    {
      "transaction_id": "txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
      "status": "succeeded"
    },
    {
      "transaction_id": "txn_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
      "status": "failed",
      "code": "NOT_FOUND",
      "message": "Transaction with ID 'txn_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30' not found"
    },
    {
      "transaction_id": "txn_7c91e4b2-3d8a-4f6e-b1c2-9a8d7e6f5b4a",
      "status": "failed",
      "code": "ALREADY_COMMITTED",
      "message": "Transaction is already committed"
    }
  ]
}

Loop through results and handle failed items by code. Queued items use status: "queued" and do not need the same error paths.

const { results } = await response.json();

for (const item of results) {
  if (item.status === "succeeded") {
    continue;
  }

  if (item.status === "queued") {
    // Item was queued for processing.
    // No error handling is needed unless your application treats queued items separately.
    continue;
  }

  if (item.status === "failed") {
    switch (item.code) {
      case "NOT_FOUND":
        // Confirm the transaction ID.
        break;
      case "ALREADY_COMMITTED":
      case "ALREADY_VOIDED":
        // Treat as already processed.
        break;
      case "LOCKED":
        // Retry shortly with backoff.
        break;
      default:
        // Handle NOT_INFLIGHT, INVALID_AMOUNT, INTERNAL_ERROR, and other failures.
        break;
    }
  }
}