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

# Errors and retries

> Handle business errors, uncertain requests and duplicate submissions.

## Inspect both error layers

Check the HTTP status and the JSON envelope's `code`, `msg` and `data`. HTTP 200 alone does not mean the business operation succeeded. For asynchronous work, accepting a request also does not mean that the task has completed.

| Result                                           | Next step                                                                              |
| ------------------------------------------------ | -------------------------------------------------------------------------------------- |
| Authentication or permission failure             | Check the credential, selected Space, membership and resource access.                  |
| Invalid request                                  | Correct fields using that endpoint's schema; preserve their types and spelling.        |
| Insufficient credits or plan restriction         | Read subscription benefits and adjust the request or plan.                             |
| Task failure                                     | Inspect its terminal status and error details before using the operation's retry path. |
| Rate limit                                       | Honor `Retry-After` when present and back off.                                         |
| Timeout or connection loss after submitting work | Query the existing task/project before submitting another generation.                  |

## Protect writes with idempotency

Send an `Idempotency-Key` of at most 128 characters for a logical write or generation request. Persist the key with the request in your application.

```bash theme={null}
curl --fail-with-body "$PODCAST_API_ORIGIN/open/podcast/v1/audio/tasks" \
  -H "X-Api-Key: $PODCAST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-42-audio-v1" \
  -d '{"project_id":"PROJECT_ID"}'
```

Keys are scoped to the account, Space, HTTP method and URI. A completed identical request replays its recorded response. Reusing the key with different content conflicts. A pending or uncertain request is not automatically executed again. Inspect its project/task before choosing a new key.

Without a key, the operation keeps its existing Web retry semantics. Idempotency replay is request history, not current project or credit state.

<Warning>Omit `Idempotency-Key` from repeated task-result POST requests and fresh credit checks. Reusing a completed key can replay an old polling response or estimate indefinitely.</Warning>

## Distinguish each task's states

Speech/audio task status `3` means success, while project status `3` means processing. Use the [status and output guide](/api-reference/guides/polling-and-outputs); do not share one numeric state enum across all task types.