Developers

Errors

An HTTP status and a JSON body with the reason.

Format

Authentication, permission and limit errors follow RFC 9457 (Content-Type: application/problem+json): 

{
  "type": "https://bm.consulting/en/developers/errors#forbidden_permission",
  "title": "Forbidden",
  "status": 403,
  "detail": "This token does not grant sales:invoices.read.",
  "code": "forbidden_permission",
  "required_permission": "sales:invoices.read",
  "error": "Forbidden"
}
FieldWhat it holds
typeLink to the explanation of the error on this page.
title · statusName and HTTP status.
detailHuman-readable explanation. It may change.
codeStable code to program against (table below).
required_permissionOn forbidden_permission: the permission the route requires.
scope · windowOn rate_limited: the level that hit the limit (token, acct or user) and the window (minute or month).
errorAlways present, kept for compatibility: the title, or the message on validation errors.

Validation errors of each operation (400, 404, 409, 422) always carry error with the reason; those raised by the API core also use the format above, with code set to http_ plus the HTTP status.

Authentication codes

codeHTTPWhen
unauthorized401The token is missing, unknown, disabled, revoked or expired.
account_bound_not_allowed403The route does not accept tokens bound to a client account.
forbidden_permission403The token lacks the route permission, given in required_permission.
ip_not_allowed403The request does not come from an IP in the token allowlist.
rate_limited429A per-minute limit or the monthly quota was reached; see window, scope and Retry-After.

Program your integration against the HTTP status and the code field. The detail and error texts are meant for people and may change.

Status codes

StatusMeaningWhen it happens
400Malformed requestA parameter or the body is not valid: invalid JSON, a date that is not ISO, a missing required field, a badly formatted amount.
401Not authenticatedThe token is missing, unknown, disabled, revoked or expired.
403ForbiddenThe token lacks the route permission (includes required_permission), the route does not accept account-bound tokens, the IP is not allowed or the resource belongs to another account.
404Not foundThe resource does not exist or belongs to another account. The API does not distinguish the two cases.
409ConflictThe operation clashes with existing data; for example, a payout identifier that is already registered.
422UnprocessableThe JSON is valid but a value breaks a business rule: an empty required field, an unknown reference.
429Too many requestsA per-minute limit or the monthly quota of the token, account or user was reached. Includes Retry-After and the X-RateLimit-* headers.
500Internal errorAn unexpected BMC failure. Retry with a delay; if it persists, write to us.
502 / 503Service unavailableA service the operation depends on (for example document storage) is not responding. Retry with a delay.

How to handle them

  • 400, 404, 409 and 422: fix the request. Retrying it unchanged gives the same result.
  • 401: check that the token is still active and valid; otherwise create or rotate another (Authentication).
  • 403: add the permission shown in required_permission to the token (Permissions) or check the IP list.
  • 429: wait the seconds given in Retry-After (Rate limits).
  • 5xx: retry with growing delays and a maximum number of attempts.
Email
Contact