Errors

How an error is written, what each member means, and how to quote it to support.

Version v1.1, updated 5 October 2026

On this page

The problem object
The errors array
Status families
Quote the request id
Related

Every error is a problem details object (RFC 9457) with a stable code. Act on the code and the status, and log the request_id.

The problem object

422 validation_failedJSON

{
  "code": "validation_failed",
  "detail": "One or more request parameters are invalid.",
  "errors": [
    {
      "field": "limit",
      "message": "must be between 1 and 200"
    }
  ],
  "instance": "/v1/categories",
  "request_id": "a1b2c3d4-0000-4000-8000-0000000000ee",
  "status": 422,
  "title": "Validation failed",
  "type": "https://birp.io/developers/errors/validation_failed"
}

Member	Meaning
`type`	The address of the documentation page of the code.
`title`	A short summary of the code.
`status`	The HTTP status, repeated in the body.
`detail`	A fixed sentence about this occurrence. It never repeats what you sent.
`instance`	The path of the request.
`code`	The stable error code. Branch on this, never on `title` or `detail`.
`request_id`	The request id, also in the `X-Request-Id` header.
`errors`	Each field, parameter or header at fault, with its `field` path and a `message`.
`required_scopes`	The scopes the operation needs, on `insufficient_scope`.
`limit_scope`	Which limit was reached, on `rate_limited`.
`current_status`	The status that refused an action, on `invalid_status_transition`, `invoice_issued` and `invoice_not_issued`.
`allowed_from`	The statuses that allow the action, on `invalid_status_transition`.
`missing_fields`	The company details an invoice still needs, on `company_profile_incomplete`.
`tax_code`, `date`	The tax code and document date that found no rule, on `no_rule_for_date`. `date` alone on `tax_rules_unavailable`.

The errors array

field is a path into what you sent: lines[1].unit_price, items[3].data.price, or a query parameter name. Fix every entry, then send the request again.

Status families

Status	What it means	What to do
400, 413, 415, 422	The request is wrong as sent.	Fix it. Sending it again unchanged gives the same answer.
401, 403	The key, its scopes or the company state refuse the call.	Fix the key or ask its company administrator.
404	The record or the route does not exist for this key.	Check the id or the path.
409	The request conflicts with the current state of a record.	Read the record, then decide.
429	A rate limit was reached.	Wait `Retry-After` seconds, then retry.
500	An unexpected error on the side of BIRP.	Retry later with the same idempotency key.

Quote the request id

When you write to support, quote the request_id and the time of the request. Never send the API key.

Every code has its own page, with its causes and fixes, in the Errors group.

handling-errors
validation-failed
not-found
rate-limits