Errors

API BCE uses conventional HTTP status codes. 2xx means success, 4xx means a problem with your request, 5xx means a problem on our side.

Status codes#

Type	Description
`400`	The request was malformed or missing a required parameter.
`401`	Missing or invalid API credentials.
`402`	Your subscription is inactive or the monthly quota is exhausted.
`403`	Your key is not allowed to access this resource.
`404`	The requested entity does not exist.
`412`	A required precondition (e.g. headers) was not met.
`429`	Hourly rate limit or monthly quota exceeded.
`500`	Something went wrong on our side. Retry later.

Errors use the same envelope; the message is in error. Quota and rate-limit errors add plan, limit and resetAt.

{
  "success": false,
  "error": "Monthly quota exceeded",
  "plan": "free",
  "limit": 1000,
  "resetAt": "2026-07-01T00:00:00.000Z"
}

ℹ️

Retry 429 and 5xx responses with exponential backoff. Do not retry 4xx errors other than 429.