Common error types

Error format

REST API errors return a JSON body with a single error object:

{
  "error": {
    "message": "Your API key is not linked to an active billing account. Please go to Boson.ai to set up billing and purchase credits.",
    "type": "insufficient_quota",
    "param": null,
    "code": "no_billing_account"
  }
}

object

message (string, human-readable), type (string, error category), param (string or null, the offending parameter if any), code (string or null, machine-readable cause).

Handle errors by type (the stable category) and use code to distinguish causes within it.

Error types

Status	`type`	Cause	Fix
`401`	`authentication_error`	Problem with your API key — missing, malformed, or revoked (`code: "invalid_api_key"`).	Check the `Authorization: Bearer` header and the key in your workspace. See Authentication.
`400` / `403`	`invalid_request_error`	Malformed request, or the key lacks access to the requested model.	Fix the request per the `message`; for model access, contact support.
`429`	`rate_limit_error`	Too many requests — transient.	Retry with backoff.
`429`	`insufficient_quota`	Billing refusal — not transient; retrying cannot succeed until the account changes. See the code table below.	Resolve in workspace billing, not in code.
`5xx`	`api_error`	Something failed on the server side.	Retry later; report if persistent.

Both rate_limit_error and insufficient_quota arrive as 429 — check error.type before retrying. A rate_limit_error recovers on its own; an insufficient_quota never does.

`insufficient_quota` codes

`code`	Meaning	Fix
`no_billing_account`	The key isn’t linked to an active billing account — typically a new account that hasn’t claimed credit.	Claim your free trial credit.
`insufficient_quota`	Credits are exhausted.	Add credits.
`monthly_cap_reached`	Your own monthly spend cap is reached.	Raise or remove the cap; it also resets at the start of each month (UTC).
`contract_ended`	The account’s contract has ended.	Contact your Boson AI representative.

Realtime errors

The Realtime WebSocket signals problems with an error server event carrying the same type / code / message / param fields. Billing refusals use type: "insufficient_quota" and are followed by WebSocket close code 4429; invalid or expired keys close with code 3000. See the close-code table for all codes.

Realtime API

Text-to-Speech API

Avatar API

Errors

Common error types

Error format

Error types

`insufficient_quota` codes

Realtime errors

Product-specific request errors

​Error format

​Error types

​insufficient_quota codes

​Realtime errors

​Product-specific request errors

Error format

Error types

`insufficient_quota` codes

Realtime errors

Product-specific request errors