> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audivo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error code the API returns, what it means, and whether a retry can help.

Every error, from either surface, is one JSON envelope:

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "code": "source_not_supported",
    "message": "Direct audio URLs are not supported. Submit an Apple Podcasts episode URL or an RSS feed URL plus GUID.",
    "doc_url": "https://docs.audivo.dev/errors#source_not_supported",
    "request_id": "req_...",
    "retryable": false
  }
}
```

`code` is the closed list below and is what to branch on; `type` is its coarser family; `message` is for a person; `retryable` says whether the identical request can succeed later without any change on your side. `doc_url` links to the heading for the code on this page.

A refusal generated at the edge itself — a missing key, a rate limit — has the same shape, with a `request_id` that carries the gateway's own hyphenated id.

## Your request

<h3 id="invalid_request">
  `invalid_request`
</h3>

**400** · retryable: no. The request shape is wrong: a missing field, a value out of range, an unknown field.

<h3 id="invalid_url">
  `invalid_url`
</h3>

**400** · retryable: no. A pointer that is not an absolute http(s) URL, or not one of the supported forms.

<h3 id="unauthenticated">
  `unauthenticated`
</h3>

**401** · retryable: no. Missing, malformed, revoked or expired API key or dashboard session.

<h3 id="payment_required">
  `payment_required`
</h3>

**402** · retryable: no. Available credits cannot cover the quote ceiling.

<h3 id="rate_limited">
  `rate_limited`
</h3>

**429** · retryable: yes. Over the plan's requests per minute; wait for `Retry-After`.

<h3 id="concurrency_limited">
  `concurrency_limited`
</h3>

**429** · retryable: yes. The plan's open-job cap is reached; wait for a job to finish.

## Quotes, confirms and groups

<h3 id="quote_not_found">
  `quote_not_found`
</h3>

**404** · retryable: no. The quote does not exist or belongs to another account.

<h3 id="quote_expired">
  `quote_expired`
</h3>

**409** · retryable: no. The quote's `expires_at` has passed; request a new quote.

<h3 id="quote_mismatch">
  `quote_mismatch`
</h3>

**409** · retryable: no. An entry's audio changed since the quote; request a new quote.

<h3 id="quote_unverified">
  `quote_unverified`
</h3>

**409** · retryable: yes. The confirm ran out of time re-checking every entry; retry the same confirm.

<h3 id="expected_total_mismatch">
  `expected_total_mismatch`
</h3>

**409** · retryable: no. Your `expected_total_credits` disagrees with the quote's `total_ceiling_credits`; nothing was spent.

<h3 id="group_not_found">
  `group_not_found`
</h3>

**404** · retryable: no. The job group does not exist or belongs to another account.

<h3 id="idempotency_conflict">
  `idempotency_conflict`
</h3>

**409** · retryable: no. The same `Idempotency-Key` was reused with a different body.

<h3 id="request_in_progress">
  `request_in_progress`
</h3>

**409** · retryable: yes. A request under this `Idempotency-Key` is still running; retry with the same key shortly.

<h3 id="nothing_to_quote">
  `nothing_to_quote`
</h3>

**422** · retryable: no. Every episode in the selection was excluded from pricing; the exclusions say why.

## Jobs and transcripts

<h3 id="job_not_found">
  `job_not_found`
</h3>

**404** · retryable: no. The job does not exist or belongs to another account.

<h3 id="job_not_completed">
  `job_not_completed`
</h3>

**409** · retryable: yes. A derived artifact was requested for a job that has not completed; poll and retry.

<h3 id="processing_failed">
  `processing_failed`
</h3>

**500** · retryable: yes. A terminal job failure; the reservation was released.

<h3 id="engine_unavailable">
  `engine_unavailable`
</h3>

**503** · retryable: yes. The pinned transcription route is unavailable; no silent switch to another engine.

## Resolving a show or episode

<h3 id="source_not_supported">
  `source_not_supported`
</h3>

**422** · retryable: no. Direct audio, uploads, Spotify- or YouTube-exclusive shows, or a feed with nothing stable to key a transcript on.

<h3 id="feed_dead">
  `feed_dead`
</h3>

**422** · retryable: yes. The feed could not be fetched or parsed within the request's budget.

<h3 id="episode_not_found">
  `episode_not_found`
</h3>

**422** · retryable: no. The episode is not in the feed, or not in the catalog when named by id.

<h3 id="show_not_found">
  `show_not_found`
</h3>

**422** · retryable: no. The show could not be resolved.

<h3 id="unsafe_source">
  `unsafe_source`
</h3>

**422** · retryable: no. The fetch target or a redirect failed the outbound-security policy.

<h3 id="unsupported_codec">
  `unsupported_codec`
</h3>

**422** · retryable: no. The audio is in a format the pipeline does not accept.

<h3 id="unsupported_language">
  `unsupported_language`
</h3>

**422** · retryable: no. The requested language is outside published support.

<h3 id="duration_exceeded">
  `duration_exceeded`
</h3>

**422** · retryable: no. The episode is longer than the published 10-hour cap.

<h3 id="size_exceeded">
  `size_exceeded`
</h3>

**422** · retryable: no. The audio file is larger than the published 5 GB cap.

<h3 id="content_blocked">
  `content_blocked`
</h3>

**451** · retryable: no. A publisher or legal block is active for this content.

<h3 id="discovery_unavailable">
  `discovery_unavailable`
</h3>

**503** · retryable: yes. The show directory did not answer.

## Your account

<h3 id="account_suspended">
  `account_suspended`
</h3>

**409** · retryable: no. The account is on hold and cannot accept this write; reads stay open.

<h3 id="account_closed">
  `account_closed`
</h3>

**409** · retryable: no. The account is closing or closed.

<h3 id="account_not_found">
  `account_not_found`
</h3>

**409** · retryable: no. The credential resolves to no account row.

<h3 id="tier_unchanged">
  `tier_unchanged`
</h3>

**409** · retryable: no. Checkout was refused because the account already holds the requested plan.

<h3 id="api_key_not_found">
  `api_key_not_found`
</h3>

**404** · retryable: no. The dashboard key does not exist or belongs to another account.

<h3 id="api_key_limit_reached">
  `api_key_limit_reached`
</h3>

**409** · retryable: no. The account already holds the maximum number of live keys; revoke one.

<h3 id="credit_lot_not_found">
  `credit_lot_not_found`
</h3>

**404** · retryable: no. The credit lot does not exist or belongs to another account.

<h3 id="credits_not_refundable">
  `credits_not_refundable`
</h3>

**422** · retryable: no. The named lots are consumed, promotional, expired or otherwise ineligible.

## Ours

<h3 id="internal_error">
  `internal_error`
</h3>

**500** · retryable: yes. An unclassified failure; retry, and quote the `request_id` if it persists.