Skip to main content
Bachs uses conventional HTTP status codes to indicate the result of a request. A 2xx code means success. A 4xx code means the request failed given the information provided, such as a missing field or a declined payment. A 5xx code means something went wrong on our side; these are rare.

The error object

When a request fails, the API returns a flat error object instead of the resource. Branch on error_code, which is stable, rather than on detail, which is a human-readable message that may change.
string
required
Stable, machine-readable code. Always present. Look it up in the Error Reference.
string
required
Human-readable description of what went wrong.
string
Optional link to an entry in the Error Reference. Some errors omit it.
array
Optional field-level details on some validation errors. When present, use each entry’s field and message to help the user correct the input. The example below also includes type; some requirement-field errors provide code instead. Handle additional entry fields without requiring either one.
object
Present on limit errors only. Structured context such as requested_amount and max_allowed_amount.

Validation errors

A VALIDATION_ERROR returns 400. It can provide only detail, or it can also include errors[] with field-level messages. Handle both shapes:
Fixed price validation (400)

HTTP status codes

For every error_code and what to do about it, see the Error Reference.

Request ID

Every response, success or error, includes an x-request-id header.
Log it, and include it when you contact support. It is the fastest way for us to locate your exact request.

Handling errors

1

Branch on error_code

Use error_code, not detail or the HTTP status alone, to drive your logic. It is stable across releases.
2

Surface validation messages

For VALIDATION_ERROR, show detail. If errors[] is present, also show each field-level message beside the relevant input.
3

Resolve uncertain writes

Back off before retrying a read after 429 or 5xx. For a write, a timeout or 5xx does not prove that nothing happened. Keep the same request and Idempotency-Key where the endpoint supports it, then follow that endpoint’s retrieval or reconciliation guidance. Do not start the same uncertain operation with a new key.
Rate limits and back-off headers (Retry-After, X-RateLimit-Reset) are documented on API Standards.

In the SDKs

The official SDKs raise BachsApiError for any error response. Its fields are named after what they hold, so the HTTP status code and the Bachs error code are never confused: See Errors in the Node.js SDK and Errors in the Python SDK.