Errors & Request Tracing - Tabs

The Tabs API uses standard HTTP response status codes to indicate the outcome of requests. Every API response includes tracing identifiers to help you debug and inspect interactions.

Error format

When an API call fails, Tabs returns a structured JSON payload:

{
  "statusCode": 400,
  "message": "accountNumber must be a 10-digit NUBAN string",
  "error": "Bad Request",
  "timestamp": "2026-09-21T02:45:12.384Z",
  "requestId": "9c1a5b48-18e3-4f9e-9d2a-4318d19a71a0"
}

Properties

Field	Type	Description
`statusCode`	integer	The HTTP status code matching the response header
`message`	string \| array	A descriptive error message or array of validation errors
`error`	string	The canonical HTTP error phrase
`timestamp`	string	ISO-8601 timestamp when the failure occurred
`requestId`	string	Unique identifier for tracing the request

HTTP status codes

Code	Status	Meaning
`200`	OK	The request succeeded and returned the requested data
`201`	Created	A new resource (payout, quote, beneficiary) was created
`400`	Bad Request	Missing required fields, invalid JSON, or failed input validation
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient key scopes, unapproved KYC status, or IP not allowed
`404`	Not Found	The requested resource (wallet, payout, beneficiary) does not exist
`409`	Conflict	Concurrent request in-flight with the same `Idempotency-Key`
`422`	Unprocessable Entity	Payload mismatch on replayed idempotency key or business logic error
`500`	Internal Server Error	An unexpected server error occurred

Request tracing with `X-Request-Id`

Every response returned by the Tabs API includes an X-Request-Id header:

X-Request-Id: 9c1a5b48-18e3-4f9e-9d2a-4318d19a71a0

Searching logs in the merchant portal

You can inspect the exact request and response headers, payloads, and latency for any call:

Open the Tabs Merchant Portal.
Go to Developers > Request Logs.
Paste the requestId into the search field.
Click the row to open the log drawer and inspect full diagnostic details.