Errors

Every error is a JSON object with code (a stable code for programs), error (a short message for people), requestId and retryable (whether repeating the same request later can succeed), plus category and severity. The request ID is also returned in the X-Request-Id header. Responses never contain a stack, a raw provider error or internal prices.

When present, acceptance: "rejected" certifies that the command was refused before acceptance. Without that confirmation, a lost response, network failure or HTTP error alone does not prove that no task was created. Retain the original body, quoteId and Idempotency-Key; check the original operation or repeat the same command. retryable does not authorize a new purchase with a different key.

An unexpected failure is 500 with the code DEVELOPER_API_ERROR (DEVELOPER_TTS_ERROR on /api/v1/tts); a failure to create an already admitted operation is 500 with PODCAST_CREATE_FAILED or NEWS_CREATE_FAILED.

For an accepted Podcast or News episode, reasons for later paid-action refusals arrive in task status, not as an HTTP response to the original create call. Low balance produces paused_insufficient_credits and is not a failure.

A provider funding wait before another model call appears in optional recovery.reasonCode: PROVIDER_FUNDING_READ_UNAVAILABLE means the check is temporarily unavailable; PROVIDER_FUNDING_INSUFFICIENT means the check measured insufficient provider funds. This is not a generation failure or low owner credit balance: retain the original operation and check its status. Invalid credentials or configuration are not treated as this automatic wait.

For failed News, task.errorCode contains only a stable product code. It does not expose quotations, private research context or provider error text. For NEWS_EVIDENCE_INSUFFICIENT, check retained material availability and ownership; for a substantive gap, refine the topic or available materials. A service or provider failure requires checking status and receipt first. Admissible retained work can continue from the Mini App; an unknown external result does not authorize a repeat without proof. Repeating creation of an accepted task with the same idempotency key returns that existing task.

Code	HTTP	When
API_KEY_REQUIRED	401	no Authorization: Bearer header
INVALID_API_KEY_FORMAT	401	the Authorization header is not Bearer <key>
INVALID_API_KEY	401	the key is not found
API_KEY_REVOKED, API_KEY_EXPIRED	401	the key is revoked or expired
API_KEY_SCOPE_DENIED	403	the key lacks the needed scope
API_KEY_RATE_LIMITED	429	the per-minute request limit is exceeded
API_KEY_QUOTA_EXCEEDED	402 or task errorCode	the key’s quota is not enough
INSUFFICIENT_CREDITS	402	the owner’s balance is not enough
OPERATION_SPENDING_LIMIT	task errorCode	the next request exceeds the episode spending limit
API_KEY_QUOTE_MISMATCH	409	the quote was issued to another key
QUOTE_FINGERPRINT_MISMATCH	409	the create body differs from the quote body
QUOTE_EXPIRED, QUOTE_ALREADY_CONSUMED	409	the quote expired or was already used
QUOTE_NOT_FOUND	404	there is no such quote
INVALID_QUOTE	400	the create or Continue body has no valid quoteId
IDEMPOTENCY_KEY_REQUIRED	400	no Idempotency-Key header
INVALID_IDEMPOTENCY_KEY	400	Idempotency-Key is not 8–128 characters of A-Za-z0-9._:-
IDEMPOTENCY_CONFLICT	409	the idempotency key was used with a different body
UNSUPPORTED_API_FIELD	400	the body has a field outside the public contract
INVALID_MODE, INVALID_TEXT, INVALID_LENGTH_PRESET, INVALID_GROUNDING, INVALID_RESEARCH_URL and other INVALID_*	400	an invalid field value
INVALID_BUDGET	400	maximumCredits is neither a positive safe integer nor null
INVALID_NEWS_TOPIC	400	the topic is neither in the catalog nor yours
INVALID_NEWS_INPUT	400	an invalid News period, voice, language or preferences
NEWS_EVIDENCE_INSUFFICIENT	task errorCode	retained materials are unavailable or their identity does not match the accepted order; synthesis does not start
NEWS_RESEARCH_UNCONFIRMED	task errorCode	discovered material could not be confirmed for the selected topic and period; choose another topic or period
NEWS_RESEARCH_INCOMPLETE	task errorCode	research is incomplete and the edition has not been created yet; check status and receipt before admissible continuation
NEWS_NARRATION_EMPTY	task errorCode	no usable accepted text is available for synthesis
NEWS_SERVICE_UNAVAILABLE, NEWS_PROVIDER_UNAVAILABLE	task errorCode	the current executor or external service cannot finish the task
NEWS_GENERATION_FAILED, VOICE_SYNTHESIS_FAILED	task errorCode	the episode or finished audio could not be created
PODCAST_NOT_FOUND, TASK_NOT_FOUND	404	no such operation, or it was created by another key
PODCAST_CONTINUATION_UNAVAILABLE	409	a failed task cannot safely continue, or confirmation does not match the original work
PODCAST_CONTINUATION_QUOTE_MISMATCH	409	the continuation quote belongs to another task revision
NEWS_NOT_READY	409	the result or audio is not ready yet
PODCAST_NOT_CANCELLABLE, NEWS_NOT_CANCELLABLE	409	the operation has already finished
CATALOG_NOT_FOUND, SERVICE_UNAVAILABLE	503	generation is temporarily unavailable on this deployment
PRICING_AUTHORITY_UNAVAILABLE	503	no usable published pricing-policy/catalog pair is available for a new quote
RESEARCH_EXTRACTION_UNAVAILABLE	503	Quick/Deep has neither an extraction route nor usable library text; quoting refuses before paid work
RANGE_NOT_SATISFIABLE	416	an invalid audio range
INVALID_JSON, INVALID_REQUEST_BODY	400	the body could not be parsed
UNSUPPORTED_BODY_ENCODING	415	an unsupported body encoding
PAYLOAD_TOO_LARGE	413	the body is larger than 10 MiB
NOT_FOUND	404	an unknown path under /api/v1/