Errors

{
  "detail": "Missing required field(s): name, price",
  "error_code": "VALIDATION_ERROR",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general",
  "errors": [
    { "field": "name", "message": "Field required", "type": "missing" },
    { "field": "price", "message": "Field required", "type": "missing" }
  ]
}

{
  "detail": "Product not found",
  "error_code": "NOT_FOUND",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "This key does not have the required scope: products:write",
  "error_code": "FORBIDDEN",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "Missing required field(s): name, price",
  "error_code": "VALIDATION_ERROR",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general",
  "errors": [
    { "field": "name", "message": "Field required", "type": "missing" },
    { "field": "price", "message": "Field required", "type": "missing" }
  ]
}

{
  "detail": "Product not found",
  "error_code": "NOT_FOUND",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "This key does not have the required scope: products:write",
  "error_code": "FORBIDDEN",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

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.

{
  "detail": "Missing required field(s): name, price",
  "error_code": "VALIDATION_ERROR",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general",
  "errors": [
    { "field": "name", "message": "Field required", "type": "missing" },
    { "field": "price", "message": "Field required", "type": "missing" }
  ]
}

{
  "detail": "Product not found",
  "error_code": "NOT_FOUND",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

{
  "detail": "This key does not have the required scope: products:write",
  "error_code": "FORBIDDEN",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

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.

{
  "detail": "Product not found",
  "error_code": "NOT_FOUND",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

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:

{
  "detail": "Missing required field(s): name, price",
  "error_code": "VALIDATION_ERROR",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general",
  "errors": [
    { "field": "name", "message": "Field required", "type": "missing" },
    { "field": "price", "message": "Field required", "type": "missing" }
  ]
}

Fixed price validation (400)

{
  "detail": "price: amount is required for a fixed price.",
  "error_code": "VALIDATION_ERROR"
}

HTTP status codes

Status	Meaning
`200`	OK. The request succeeded.
`201`	Created. A new resource was created.
`204`	No Content. The request succeeded with no body (deletes).
`400`	Bad Request. The request was unacceptable, often a missing or invalid parameter. Request validation errors (`VALIDATION_ERROR`) use this status, with field-level `errors[]` when available.
`401`	Unauthorized. No valid API key was provided.
`403`	Forbidden. The key lacks permission for this action.
`404`	Not Found. The resource does not exist in your scope.
`409`	Conflict. The request conflicts with the current state, such as a duplicate.
`422`	Unprocessable. The request was well-formed, but a business rule rejected it, for example an unsupported checkout currency.
`428`	Precondition Required. A required precondition is missing.
`429`	Too Many Requests. You hit the rate limit. Back off and retry.
`500`, `502`, `503`	Server Errors. Something went wrong on our side. These are rare.

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.

x-request-id: 2f31edcd-0bba-4a89-98b9-533921e42f26

Log it, and include it when you contact support. It is the fastest way for us to locate your exact request.

Handling errors

Branch on error_code

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

Surface validation messages

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

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.

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Media

Misc

Transfers

Persons

Platform Fees

Reference

The error object

Validation errors

HTTP status codes

Request ID

Handling errors

​The error object

​Validation errors

​HTTP status codes

​Request ID

​Handling errors

The error object

Validation errors

HTTP status codes

Request ID

Handling errors