# Sonilo API errors, authentication, and rate limits

Canonical docs: https://platform.sonilo.com/docs/errors
OpenAPI markdown: https://platform.sonilo.com/openapi.md
OpenAPI JSON: https://platform.sonilo.com/openapi.json
Source path: /docs/api/errors
Runtime API host: https://api.sonilo.com/v1

Use this page when agents visit /docs/errors, /docs/error-codes, /docs/api/errors, /api-reference/errors, or /reference/errors and need a text/markdown answer instead of the interactive docs shell.

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Authentication

- Send Authorization: Bearer sk_your_api_key from server-side code only.
- Never expose SONILO_API_KEY in browser JavaScript, HTML, source maps, logs, JSON responses, generated files, or final text.
- Treat 401 auth_invalid as a missing, invalid, revoked, or incorrectly sent API key.

## Common error codes

- 400 bad_request or validation error: correct fields, prompt, duration, file type, URL, or endpoint-specific input.
- 401 auth_invalid or auth_required: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits or balance before retrying; do not create fake or placeholder audio.
- 403 forbidden or service_disabled: the key is valid but account or service permission is missing. Check GET /v1/account/services.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 422 unprocessable_entity: the input is structurally valid but cannot be processed, such as a video endpoint receiving a file with no video track.
- 429 rate_limit_exceeded: honor Retry-After when present; otherwise retry with bounded exponential backoff.
- 5xx upstream_error: retry only with bounded backoff and surface an actionable failure if it persists.

## Endpoint recovery checklist

- Music from text: POST /v1/text-to-music.
- Music from video: POST /v1/video-to-music.
- Prompt-only sound effects: POST /v1/text-to-sfx.
- Sound effects synchronized to video clips: POST /v1/video-to-sfx.
- Narration or voice over background music: POST /v1/audio-ducking.
- Async task polling: GET /v1/tasks/{task_id}.
- Account services: GET /v1/account/services.
- Usage and credits: GET /v1/account/usage?days=30.

## Coding-agent guidance

- If a request fails with 401, 402, 403, 422, or 429, classify the API state and report it. Do not switch endpoints just to hide the failure.
- If a task asks for generated files, create complete files with apply_patch or an equivalent captured file-edit mechanism before the final response.
- Verify with syntax checks, smoke tests, and bounded live API calls when SONILO_API_KEY is present.
- Save real API output files only after the API succeeds. If the account has insufficient balance, report that state instead of creating fake or placeholder audio.