HTTP statuses, the error body shape, and every error code with its fix.
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").
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.
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.Any other error leaves the session open. When a response fails, its response.done follows with status: "failed". A rate limit there is type: "rate_limit_error", code: "rate_limit_exceeded", and is transient like its REST counterpart: retry with response.create. See the error event for the response-failure codes.
Speech WebSocket errors
The speech WebSocket (/v1/audio/speech/live) sends a flat error event, {"type": "error", "code": "...", "message": "..."}, with no nested error object and no param. Authentication, rate-limit, and billing refusals use the same code values as the REST API (invalid_api_key, rate_limit_exceeded, and the insufficient_quota codes above). Some errors leave the session open; the others are followed by a standard close code: 1008 for refusals and limits, 1011 for a server error while generating audio, or 1000 after an idle timeout. A session counts once against your rate limit, and each API key can currently have one session open. See the error-code table for all codes.
If an error persists or doesn’t match this page, report it with the full error object and a timestamp.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Boson","description":"Build with Higgs Realtime, Higgs TTS 3, and Higgs Avatar APIs.","colors":{"primary":"#17B726","light":"#3DD24A","dark":"#1D7028"},"logo":{"light":"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/boson_ai_logo.svg?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=a612c3151ec7dfaae986ba9f8053392b","dark":"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/logo_light.svg?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=2aa7370dbe21e0a611129de5bd0dd16d"},"favicon":"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/favicon.ico?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=24cc72e718eee5ab1ef7451dd1624648","navbar":{"links":[{"href":"/feedback","label":"Feedback"}],"primary":{"type":"button","label":"Workspace","href":"https://www.boson.ai/workspace"}},"footer":{"socials":{"x":"https://x.com/boson_ai","github":"https://github.com/boson-ai"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"bosonai","hasAudioNarration":false,"actualSubdomain":"bosonai","customDomains":["docs.boson.ai"],"gitSource":{"type":"github","owner":"boson-ai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6af786528d326e366b9e4791","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"Documentation","count":30},{"language":"default","tag":"API Reference","count":23},{"language":"default","tag":"Higgs Realtime","count":9},{"language":"default","tag":"Avatar Realtime API","count":8},{"language":"default","tag":"Higgs TTS 3","count":7},{"language":"default","tag":"Text-to-Speech API","count":6},{"language":"default","tag":"Get started","count":6},{"language":"default","tag":"Realtime API","count":4},{"language":"default","tag":"Higgs Avatar","count":4},{"language":"default","tag":"Guides","count":4}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"#sidebar [data-sidebar-group-title],#sidebar .sidebar-group-title,#sidebar [class*=\"GroupTitle\"],aside [data-sidebar-group-title],aside .sidebar-group-title,aside [class*=\"GroupTitle\"],nav[aria-label=\"Sidebar\"] li>h5,nav[aria-label=\"Sidebar\"] li>h4,nav[aria-label=\"Sidebar\"] li>div[class*=\"font-semibold\"]:first-child{font-size:0.7rem!important;font-weight:600!important;letter-spacing:0.08em!important;text-transform:uppercase!important;color:rgb(115, 115, 115)!important;margin-top:1.25rem!important;margin-bottom:0.5rem!important}html.dark #sidebar [data-sidebar-group-title],html.dark #sidebar .sidebar-group-title,html.dark #sidebar [class*=\"GroupTitle\"],html.dark aside [data-sidebar-group-title],html.dark aside .sidebar-group-title,html.dark aside [class*=\"GroupTitle\"],html.dark nav[aria-label=\"Sidebar\"] li>h5,html.dark nav[aria-label=\"Sidebar\"] li>h4,html.dark nav[aria-label=\"Sidebar\"] li>div[class*=\"font-semibold\"]:first-child{color:rgb(160, 160, 160)!important}main table th:not(:last-child),main table td:not(:last-child){white-space:nowrap;width:1%}main table th:last-child,main table td:last-child{width:auto;min-width:14rem;white-space:normal}main table th,main table td{vertical-align:middle!important}@media (max-width: 640px){main .expand-schema-container,main .expand-schema-container>div,main .expand-schema-container .border-none,main .expand-schema-container .font-mono.font-bold,main .expand-schema-container .text-xs.truncate{max-width:100%;min-width:0}}main .realtime-event-catalog>p,main .realtime-event-catalog>[data-as=\"p\"],main .realtime-event-catalog>ul,main .realtime-event-catalog>ol{font-size:0.875rem;line-height:1.5rem}main .realtime-event-catalog>[data-as=\"p\"]{display:block;margin-top:1.25em;margin-bottom:1.25em}main .realtime-event-catalog>h2{font-size:1.125rem;line-height:1.6875rem}main .realtime-event-catalog>h3{font-size:1rem;line-height:1.5rem}main .realtime-event-catalog table{font-size:0.8125rem;line-height:1.25rem;table-layout:auto;width:100%}main .realtime-event-catalog table th,main .realtime-event-catalog table td,main .realtime-event-catalog table th:not(:last-child),main .realtime-event-catalog table td:not(:last-child),main .realtime-event-catalog table th:last-child,main .realtime-event-catalog table td:last-child{min-width:0;white-space:normal;width:auto}main .realtime-event-catalog table code{overflow-wrap:anywhere;word-break:break-word}main .wrap-table table th,main .wrap-table table td,main .wrap-table table th:not(:last-child),main .wrap-table table td:not(:last-child),main .wrap-table table th:last-child,main .wrap-table table td:last-child{min-width:0;white-space:normal;width:auto}main .wrap-table table code{overflow-wrap:anywhere}main .tags-sample-tables table{border-collapse:separate;border-spacing:0 0.75rem;display:block;width:100%}main .tags-sample-tables table thead{display:none}main .tags-sample-tables table tbody{display:grid;gap:0.75rem}main .tags-sample-tables table tr{border:1px solid rgb(229, 229, 229);border-radius:0.5rem;display:grid;gap:0.5rem 1rem;grid-template-columns:minmax(8rem, max-content) 1fr 14rem;padding:0.875rem 1rem}html.dark main .tags-sample-tables table tr{border-color:rgb(64, 64, 64)}main .tags-sample-tables table td{border:0!important;padding:0!important;white-space:normal!important;width:auto}main .tags-sample-tables table td::before{color:rgb(115, 115, 115);display:block;font-size:0.75rem;font-weight:600;margin-bottom:0.125rem}html.dark main .tags-sample-tables table td::before{color:rgb(160, 160, 160)}main .tags-sample-tables table td:nth-child(1)::before{content:\"Tag\"}main .tags-sample-tables table td:nth-child(1) code{background:rgb(237, 247, 237);border:1px solid rgb(188, 220, 188);color:rgb(29, 112, 40);font-weight:700}html.dark main .tags-sample-tables table td:nth-child(1) code{background:rgba(34, 197, 94, 0.12);border-color:rgba(34, 197, 94, 0.35);color:rgb(134, 239, 172)}main .tags-sample-tables table td:nth-child(2)::before{content:\"Effect\"}main .tags-sample-tables table td:nth-child(3)::before{content:\"Sample input\"}main .tags-sample-tables table td:nth-child(4)::before{content:\"Sample audio\"}main .tags-sample-tables table td:nth-child(2){grid-column:2 / -1}main .tags-sample-tables table td:nth-child(3){grid-column:1 / 3}main .tags-sample-tables table td:nth-child(4){grid-column:3 / 4;grid-row:2}main .tags-sample-tables table td:nth-child(3) code{display:inline;overflow-wrap:anywhere;word-break:break-word;white-space:normal}main .tags-sample-tables table audio{display:block;max-width:100%;width:14rem}main .voice-sample-tables table{border-collapse:separate;border-spacing:0 0.75rem;display:block;width:100%}main .voice-sample-tables table thead{display:none}main .voice-sample-tables table tbody{display:grid;gap:0.75rem}main .voice-sample-tables table tr{border:1px solid rgb(229, 229, 229);border-radius:0.5rem;display:grid;gap:0.5rem 1rem;grid-template-columns:minmax(6rem, max-content) 1fr 14rem;padding:0.875rem 1rem}html.dark main .voice-sample-tables table tr{border-color:rgb(64, 64, 64)}main .voice-sample-tables table td{border:0!important;padding:0!important;white-space:normal!important;width:auto}main .voice-sample-tables table td::before{color:rgb(115, 115, 115);display:block;font-size:0.75rem;font-weight:600;margin-bottom:0.125rem}html.dark main .voice-sample-tables table td::before{color:rgb(160, 160, 160)}main .voice-sample-tables table td:nth-child(1)::before{content:\"Voice\"}main .voice-sample-tables table td:nth-child(1) code{background:rgb(237, 247, 237);border:1px solid rgb(188, 220, 188);color:rgb(29, 112, 40);font-weight:700}html.dark main .voice-sample-tables table td:nth-child(1) code{background:rgba(34, 197, 94, 0.12);border-color:rgba(34, 197, 94, 0.35);color:rgb(134, 239, 172)}main .voice-sample-tables table td:nth-child(2)::before{content:\"Style\"}main .voice-sample-tables table td:nth-child(3)::before{content:\"Sample input\"}main .voice-sample-tables table td:nth-child(4)::before{content:\"Sample audio\"}main .voice-sample-tables table td:nth-child(2){grid-column:2 / -1}main .voice-sample-tables table td:nth-child(3){grid-column:1 / 3}main .voice-sample-tables table td:nth-child(4){grid-column:3 / 4;grid-row:2}main .voice-sample-tables table td:nth-child(3) code{display:inline;overflow-wrap:anywhere;word-break:break-word;white-space:normal}main .voice-sample-tables table audio{display:block;max-width:100%;width:14rem}main .fine-control-sample-table table{border-collapse:separate;border-spacing:0;display:block;width:100%}main .fine-control-sample-table table thead{display:none}main .fine-control-sample-table table tr{border:1px solid rgb(229, 229, 229);border-radius:0.5rem;display:grid;gap:0.5rem 1rem;grid-template-columns:1fr 14rem;padding:0.875rem 1rem}html.dark main .fine-control-sample-table table tr{border-color:rgb(64, 64, 64)}main .fine-control-sample-table table td{border:0!important;padding:0!important;white-space:normal!important;width:auto!important}main .fine-control-sample-table table td::before{color:rgb(115, 115, 115);display:block;font-size:0.75rem;font-weight:600;margin-bottom:0.125rem}html.dark main .fine-control-sample-table table td::before{color:rgb(160, 160, 160)}main .fine-control-sample-table table td:nth-child(1)::before{content:\"Sample input\"}main .fine-control-sample-table table td:nth-child(2)::before{content:\"Sample audio\"}main .fine-control-sample-table table td:nth-child(1) code{display:inline;overflow-wrap:anywhere;word-break:break-word;white-space:normal}main .fine-control-sample-table table audio{display:block;margin-top:0.35rem;max-width:100%;width:14rem}img[src*=\"boson_ai_logo\"],img[src*=\"logo_light\"]{height:1.5rem!important;max-height:1.5rem!important;width:auto!important}@media (max-width: 768px){main table{display:block;max-width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch}main table td:last-child,main table th:last-child{min-width:16rem}main .tags-sample-tables table tr{display:block;min-width:0;width:100%}main .tags-sample-tables table tbody,main .tags-sample-tables table td{display:block;min-width:0!important;width:100%!important}main .tags-sample-tables table td+td{margin-top:0.45rem}main .tags-sample-tables table audio{width:12rem}main .voice-sample-tables table tr{display:block;min-width:0;width:100%}main .voice-sample-tables table tbody,main .voice-sample-tables table td{display:block;min-width:0!important;width:100%!important}main .voice-sample-tables table td+td{margin-top:0.45rem}main .voice-sample-tables table audio{width:12rem}main .fine-control-sample-table table tr{display:block;min-width:0;width:100%}main .fine-control-sample-table table td{display:block;min-width:0!important;width:100%!important}main .fine-control-sample-table table td+td{margin-top:0.45rem}main .fine-control-sample-table table audio{width:12rem}}#content-area:has(.speech-live-page)>#pagination{margin-top:2.5rem}"}]}
{"page":{"pagePath":"api-reference/errors","slug":"/api-reference/errors","pageMetadata":{"title":"Common error types","description":"HTTP statuses, the error body shape, and every error code with its fix.","href":"/api-reference/errors"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"HTTP statuses, the error body shape, and every error code with its fix.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,ResponseField,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`error-format`,children:`Error format`}),`\n`,_jsxs(_components.p,{children:[`REST API errors return a JSON body with a single `,_jsx(_components.code,{children:`error`}),` object:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Your API key is not linked to an active billing account. Please go to Boson.ai to set up billing and purchase credits.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"insufficient_quota\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"param\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`null`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"no_billing_account\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(ResponseField,{name:`error`,type:`object`,id:`param-error`,children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`message`}),` (string, human-readable), `,_jsx(_components.code,{children:`type`}),` (string, error category), `,_jsx(_components.code,{children:`param`}),` (string or null, the offending parameter if any), `,_jsx(_components.code,{children:`code`}),` (string or null, machine-readable cause).`]})}),`\n`,_jsxs(_components.p,{children:[`Handle errors by `,_jsx(_components.code,{children:`type`}),` (the stable category) and use `,_jsx(_components.code,{children:`code`}),` to distinguish causes within it.`]}),`\n`,_jsx(Heading,{level:`2`,id:`error-types`,children:`Error types`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:_jsx(_components.code,{children:`type`})}),_jsx(_components.th,{children:`Cause`}),_jsx(_components.th,{children:`Fix`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`401`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`authentication_error`})}),_jsxs(_components.td,{children:[`Problem with your API key — missing, malformed, or revoked (`,_jsx(_components.code,{children:`code: \"invalid_api_key\"`}),`).`]}),_jsxs(_components.td,{children:[`Check the `,_jsx(_components.code,{children:`Authorization: Bearer`}),` header and the key in your `,_jsx(_components.a,{href:`https://www.boson.ai/workspace/api-key`,children:`workspace`}),`. See `,_jsx(_components.a,{href:`/authentication`,children:`Authentication`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{\"data-numeric\":`true`,children:[_jsx(_components.code,{children:`400`}),` / `,_jsx(_components.code,{children:`403`})]}),_jsx(_components.td,{children:_jsx(_components.code,{children:`invalid_request_error`})}),_jsx(_components.td,{children:`Malformed request, or the key lacks access to the requested model.`}),_jsxs(_components.td,{children:[`Fix the request per the `,_jsx(_components.code,{children:`message`}),`; for model access, contact support.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`429`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`rate_limit_error`})}),_jsxs(_components.td,{children:[`Too many requests — `,_jsx(_components.strong,{children:`transient`}),`.`]}),_jsx(_components.td,{children:`Retry with backoff.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`429`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`insufficient_quota`})}),_jsxs(_components.td,{children:[`Billing refusal — `,_jsx(_components.strong,{children:`not transient`}),`; retrying cannot succeed until the account changes. See the code table below.`]}),_jsxs(_components.td,{children:[`Resolve in `,_jsx(_components.a,{href:`https://www.boson.ai/workspace/billing/overview`,children:`workspace billing`}),`, not in code.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`5xx`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`api_error`})}),_jsx(_components.td,{children:`Something failed on the server side.`}),_jsxs(_components.td,{children:[`Retry later; `,_jsx(_components.a,{href:`/feedback`,children:`report it`}),` if it persists.`]})]})]})]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Both `,_jsx(_components.code,{children:`rate_limit_error`}),` and `,_jsx(_components.code,{children:`insufficient_quota`}),` arrive as `,_jsx(_components.code,{children:`429`}),` — check `,_jsx(_components.code,{children:`error.type`}),` before retrying. A `,_jsx(_components.code,{children:`rate_limit_error`}),` recovers on its own; an `,_jsx(_components.code,{children:`insufficient_quota`}),` never does.`]})}),`\n`,_jsxs(Heading,{level:`3`,id:`insufficient_quota-codes`,children:[_jsx(_components.code,{children:`insufficient_quota`}),` codes`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:_jsx(_components.code,{children:`code`})}),_jsx(_components.th,{children:`Meaning`}),_jsx(_components.th,{children:`Fix`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`no_billing_account`})}),_jsx(_components.td,{children:`The key isn’t linked to an active billing account — typically a new account that hasn’t claimed credit.`}),_jsxs(_components.td,{children:[_jsx(_components.a,{href:`/free-trial-credit`,children:`Claim your free trial credit`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`insufficient_quota`})}),_jsx(_components.td,{children:`Credits are exhausted.`}),_jsxs(_components.td,{children:[_jsx(_components.a,{href:`/account-billing/payment-and-credits`,children:`Add credits`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`monthly_cap_reached`})}),_jsxs(_components.td,{children:[`Your own `,_jsx(_components.a,{href:`/account-billing/usage-and-limits`,children:`monthly spend cap`}),` is reached.`]}),_jsx(_components.td,{children:`Raise or remove the cap; it also resets at the start of each month (UTC).`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`contract_ended`})}),_jsx(_components.td,{children:`The account’s contract has ended.`}),_jsx(_components.td,{children:`Contact your Boson AI representative.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`realtime-errors`,children:`Realtime errors`}),`\n`,_jsxs(_components.p,{children:[`The Realtime WebSocket signals problems with an `,_jsxs(_components.a,{href:`/api-reference/realtime/server-events#error`,children:[_jsx(_components.code,{children:`error`}),` server event`]}),` carrying the same `,_jsx(_components.code,{children:`type`}),` / `,_jsx(_components.code,{children:`code`}),` / `,_jsx(_components.code,{children:`message`}),` / `,_jsx(_components.code,{children:`param`}),` fields. Billing refusals use `,_jsx(_components.code,{children:`type: \"insufficient_quota\"`}),` and are followed by WebSocket close code `,_jsx(_components.code,{children:`4429`}),`; invalid or expired keys close with code `,_jsx(_components.code,{children:`3000`}),`. See the `,_jsx(_components.a,{href:`/api-reference/realtime/overview`,children:`close-code table`}),` for all codes.`]}),`\n`,_jsxs(_components.p,{children:[`Any other `,_jsx(_components.code,{children:`error`}),` leaves the session open. When a response fails, its `,_jsx(_components.code,{children:`response.done`}),` follows with `,_jsx(_components.code,{children:`status: \"failed\"`}),`. A rate limit there is `,_jsx(_components.code,{children:`type: \"rate_limit_error\"`}),`, `,_jsx(_components.code,{children:`code: \"rate_limit_exceeded\"`}),`, and is transient like its REST counterpart: retry with `,_jsx(_components.code,{children:`response.create`}),`. See the `,_jsxs(_components.a,{href:`/api-reference/realtime/server-events#error`,children:[_jsx(_components.code,{children:`error`}),` event`]}),` for the response-failure codes.`]}),`\n`,_jsx(Heading,{level:`2`,id:`speech-websocket-errors`,children:`Speech WebSocket errors`}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.a,{href:`/api-reference/tts/speech-live`,children:`speech WebSocket`}),` (`,_jsx(_components.code,{children:`/v1/audio/speech/live`}),`) sends a flat `,_jsx(_components.code,{children:`error`}),` event, `,_jsx(_components.code,{children:`{\"type\": \"error\", \"code\": \"...\", \"message\": \"...\"}`}),`, with no nested `,_jsx(_components.code,{children:`error`}),` object and no `,_jsx(_components.code,{children:`param`}),`. Authentication, rate-limit, and billing refusals use the same `,_jsx(_components.code,{children:`code`}),` values as the REST API (`,_jsx(_components.code,{children:`invalid_api_key`}),`, `,_jsx(_components.code,{children:`rate_limit_exceeded`}),`, and the `,_jsx(_components.code,{children:`insufficient_quota`}),` codes above). Some errors leave the session open; the others are followed by a standard close code: `,_jsx(_components.code,{children:`1008`}),` for refusals and limits, `,_jsx(_components.code,{children:`1011`}),` for a server error while generating audio, or `,_jsx(_components.code,{children:`1000`}),` after an idle timeout. A session counts once against your rate limit, and each API key can currently have one session open. See the `,_jsx(_components.a,{href:`/models/higgs-tts/streaming#errors`,children:`error-code table`}),` for all codes.`]}),`\n`,_jsx(Heading,{level:`2`,id:`product-specific-request-errors`,children:`Product-specific request errors`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/models/higgs-avatar/input-options#input-limits`,children:`Avatar input limits and request errors`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/api-reference/avatar-realtime/overview#errors`,children:`Avatar realtime session errors`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/custom-voices-and-avatars#errors`,children:`Custom voice and avatar upload errors`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/models/higgs-realtime/guides/connections-and-sessions`,children:`Realtime session limits`})}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`report-a-problem`,children:`Report a problem`}),`\n`,_jsxs(_components.p,{children:[`If an error persists or doesn’t match this page, `,_jsx(_components.a,{href:`/feedback`,children:`report it`}),` with the full `,_jsx(_components.code,{children:`error`}),` object and a timestamp.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Common error types","description":"HTTP statuses, the error body shape, and every error code with its fix.","href":"/api-reference/errors"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Error format","slug":"error-format","depth":2,"children":[]},{"title":"Error types","slug":"error-types","depth":2,"children":[{"title":"insufficient_quota codes","slug":"insufficient_quota-codes","depth":3,"children":[]}]},{"title":"Realtime errors","slug":"realtime-errors","depth":2,"children":[]},{"title":"Speech WebSocket errors","slug":"speech-websocket-errors","depth":2,"children":[]},{"title":"Product-specific request errors","slug":"product-specific-request-errors","depth":2,"children":[]},{"title":"Report a problem","slug":"report-a-problem","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"bosonai","siteName":"Boson","title":"Common error types - Boson","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-12T22:05:00.422Z","originalFileLocation":"api-reference/errors.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"HTTP statuses, the error body shape, and every error code with its fix.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Boson\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Common error types - Boson\">\u003cmeta data-mint-head property=\"og:description\" content=\"HTTP statuses, the error body shape, and every error code with its fix.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Boson\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.boson.ai/api-reference/errors\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://bosonai.mintlify.site/_mintlify/api/og/v2?division=Errors\u0026amp;title=Common+error+types\u0026amp;description=HTTP+statuses%2C+the+error+body+shape%2C+and+every+error+code+with+its+fix.\u0026amp;theme=018ed43312581b1861d7483a\u0026amp;signature=c9650d301b2461c775b3659d5bf6078065389627b12bf5df8fc85e14dc4ac996\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Common error types - Boson\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"HTTP statuses, the error body shape, and every error code with its fix.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://bosonai.mintlify.site/_mintlify/api/og/v2?division=Errors\u0026amp;title=Common+error+types\u0026amp;description=HTTP+statuses%2C+the+error+body+shape%2C+and+every+error+code+with+its+fix.\u0026amp;theme=018ed43312581b1861d7483a\u0026amp;signature=c9650d301b2461c775b3659d5bf6078065389627b12bf5df8fc85e14dc4ac996\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Boson\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#17B726\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.boson.ai/api-reference/errors\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/errors.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.boson.ai/#organization\",\"name\":\"Boson\",\"url\":\"https://docs.boson.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/boson_ai_logo.svg?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=a612c3151ec7dfaae986ba9f8053392b\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.boson.ai#website\",\"name\":\"Boson\",\"url\":\"https://docs.boson.ai\",\"publisher\":{\"@id\":\"https://docs.boson.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.boson.ai/api-reference/errors#webpage\",\"url\":\"https://docs.boson.ai/api-reference/errors\",\"name\":\"Common error types\",\"description\":\"HTTP statuses, the error body shape, and every error code with its fix.\",\"dateModified\":\"2026-11-12T22:05:00.422Z\",\"isPartOf\":{\"@id\":\"https://docs.boson.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.boson.ai/api-reference/errors#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.boson.ai/api-reference/errors#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Boson\",\"item\":\"https://docs.boson.ai\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Common error types\",\"item\":\"https://docs.boson.ai/api-reference/errors\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.boson.ai/api-reference/errors#article\",\"headline\":\"Common error types\",\"name\":\"Common error types\",\"description\":\"HTTP statuses, the error body shape, and every error code with its fix.\",\"url\":\"https://docs.boson.ai/api-reference/errors\",\"mainEntityOfPage\":{\"@id\":\"https://docs.boson.ai/api-reference/errors#webpage\"},\"dateModified\":\"2026-11-12T22:05:00.422Z\",\"publisher\":{\"@id\":\"https://docs.boson.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.boson.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Boson\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Boson\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/errors.md","siteName":"Boson","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/overview"}]},{"tab":"API Reference","groups":[{"group":"Realtime API","pages":[{"title":"Overview","href":"/api-reference/realtime/overview"},{"title":"Create a client secret","openapi":"openapi.json POST /v1/realtime/client_secrets","playground":"simple","href":"/api-reference/realtime/client-secrets"},{"title":"Client events","asyncapi":"asyncapi.json clientEvents","href":"/api-reference/realtime/client-events"},{"title":"Server events","asyncapi":"asyncapi.json serverEvents","href":"/api-reference/realtime/server-events"}]},{"group":"Text-to-Speech API","pages":[{"title":"Create a speech","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/audio/speech","href":"/api-reference/audio/create-a-speech"},{"title":"Speech WebSocket","asyncapi":"asyncapi-speech.json speechLive","playground":"simple","href":"/api-reference/tts/speech-live"},{"title":"Create a voice","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/audio/voices","href":"/api-reference/audio/create-a-voice"},{"title":"List voices","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/audio/voices","href":"/api-reference/audio/list-voices"},{"title":"Get a voice","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/audio/voices/{voice}","href":"/api-reference/audio/get-a-voice"},{"title":"Delete a voice","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/audio/voices/{voice}","href":"/api-reference/audio/delete-a-voice"}]},{"group":"Avatar API","pages":[{"title":"Create a video","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/videos","href":"/api-reference/videos/create-a-video"},{"title":"Retrieve a video","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/videos/{video_id}","href":"/api-reference/videos/retrieve-a-video"},{"title":"Download content","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/videos/{video_id}/content","href":"/api-reference/videos/download-content"},{"title":"Create a video (streaming)","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/videos/stream","href":"/api-reference/videos/create-a-video-streaming"}]},{"group":"Avatar Realtime API","pages":[{"title":"Overview","href":"/api-reference/avatar-realtime/overview"},{"title":"Create a session","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/avatar/sessions","href":"/api-reference/avatar-realtime/create-a-session"},{"title":"Retrieve a session","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/avatar/sessions/{session_id}","href":"/api-reference/avatar-realtime/retrieve-a-session"},{"title":"Release a session","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/avatar/sessions/{session_id}","href":"/api-reference/avatar-realtime/release-a-session"},{"title":"List avatars","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/avatars","href":"/api-reference/avatar-realtime/list-avatars"},{"title":"Upload an avatar","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/avatars","href":"/api-reference/avatar-realtime/upload-an-avatar"},{"title":"Retrieve an avatar","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/avatars/{avatar_id}","href":"/api-reference/avatar-realtime/retrieve-an-avatar"},{"title":"Delete an avatar","description":"Delete one of your account's avatars. New sessions can no longer use it. Presets cannot be deleted.","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/avatars/{avatar_id}","href":"/api-reference/avatar-realtime/delete-an-avatar"}]},{"group":"Errors","pages":[{"title":"Common error types","href":"/api-reference/errors"}]}]}]},"basePath":"","title":"Common error types - Boson","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":[],"chunks":[]}