Handling errors

Brrndops uses standard HTTP status codes. 2xx means success, 4xx means something about the request needs to change, and 5xx means something went wrong on our side.

Every error has the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "currency is required.",
    "param": "currency",
    "request_id": "8b1f6c2e-…"
  }
}

Field	Use it to
type	Decide broadly how to react (see below).
code	Handle specific cases in code. Codes are stable.
message	Show or log a human-readable explanation. Wording may change: don’t match on it.
param	Highlight the field that caused the problem.
request_id	Find the request in Request logs, or give it to support.

Error types

Type	Status	What to do
authentication_error	401, 402	Check the API key, or the account’s plan.
permission_error	403	The key lacks a scope, or the business isn’t verified.
invalid_request_error	400, 404, 409, 413, 422	Fix the request; retrying it unchanged will fail again.
rate_limit_error	429	Slow down and retry with backoff.
api_error	500	Retry with backoff and the same idempotency key.

Error codes

Authentication and access

Code	Status	Meaning
missing_api_key	401	No Authorization header.
invalid_api_key	401	The key doesn’t exist.
api_key_expired	401	The key passed its expiry date.
api_key_revoked	401	The key was revoked.
subscription_inactive	402	Production key, but the account has no active plan.
insufficient_scope	403	The key isn’t allowed to call this endpoint.
account_not_verified	403	Production key, but business verification isn’t approved.

Request problems

Code	Status	Meaning
parameter_missing	400	A required field is missing; see param.
parameter_invalid	400	A field has an invalid value; see param and message.
parameter_unknown	400	The body contains a field the API doesn’t accept (often a typo).
invalid_json	400	The body isn’t valid JSON.
body_missing	400	The endpoint needs a JSON body.
request_too_large	413	The body is over 2MB.
resource_missing	404	No such object in this environment.

Invoices

Code	Status	Meaning
invoice_number_taken	409	Another invoice already uses this number.
amount_too_large	400	An amount exceeds 9,999,999,999 minor units.
invalid_status_transition	400	The status change isn’t allowed; see the lifecycle.
invoice_deleted	400	The invoice is deleted and can’t be changed, rendered or sent.
invoice_not_sendable	400	Draft invoices can’t be sent. Open them first.

Idempotency

Code	Status	Meaning
idempotency_key_invalid	400	The key must be 1–255 printable ASCII characters.
idempotency_key_reused	422	This key was used with a different request.
request_in_progress	409	A request with this key is still running. Retry shortly.

Server

Code	Status	Meaning
internal_error	500	Something failed on our side. Retry with backoff; contact support with the request_id if it persists.