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

required

Link to this code’s entry in the Error Reference.

array

Present on validation errors only. One entry per field that failed, each with field, message, and type.

object

Present on limit errors only. Structured context such as requested_amount and max_allowed_amount.

Validation errors

A VALIDATION_ERROR adds an errors array naming each field that failed, so you can surface the message next to the right input.

{
  "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" }
  ]
}

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.
`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`	Validation Error. One or more fields failed validation.
`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 each errors[].message next to its field in your form.

Retry transient failures safely

On 429 or a 5xx, back off and retry. For POST requests, reuse the same Idempotency-Key so the retry cannot double up.

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

Payouts

Payout Destinations

Balance

Virtual accounts

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