API errors

Use this guide to handle Sonilo API failures, authentication problems, rate limits, and async task errors.

Error format

Non-streaming errors return JSON with a stable code and a human-readable message. Use the HTTP status for retry and billing logic; use code for user-facing handling.

{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Try again in 30s."
}

Status codes

Code	Condition
400	Invalid request shape, conflicting inputs, missing required fields, or unsupported parameters.
401	API key is missing, invalid, revoked, or not sent as Authorization: Bearer sk_your_api_key.
402	Branch on the code field. trial_exhausted means the free trial for that service is spent and the account has never been funded — add a payment method. insufficient_balance means a funded wallet ran out — add balance and retry. payment_required covers the remaining cases, such as a suspended account or an exceeded credit limit.
403	API key is valid, but the account or workspace cannot access this endpoint.
413	Uploaded file exceeds the endpoint size limit.
422	The input is syntactically valid but cannot be processed, such as an over-limit duration.
429	Rate limit or concurrency limit exceeded. Retry with backoff.
502	Upstream generation provider failed or timed out. Retry the request.

Eval verification

For generation smoke tests, mark the run as passed only when the expected output file exists and is larger than 0 bytes. For the text-to-music minimal workflow, require output.m4a after the complete stream event. Do not create placeholder media files after failed API calls.

When HTTP 402 returns trial_exhausted, the account has used every free trial call for that service and has never added funds. Prompt the user to add a payment method rather than retrying. When it returns insufficient_balance, a funded wallet ran dry — add balance and retry the same request. Branch on code, never on the message text.

Authentication failures

Send Authorization: Bearer sk_your_api_key on every API request to https://api.sonilo.com/v1. Store real keys server-side, commonly as SONILO_API_KEY.

curl https://api.sonilo.com/v1/account/services \
  -H "Authorization: Bearer sk_your_api_key"

Use 401 for missing or invalid credentials. Use 403 for a valid key that lacks access to the requested endpoint or workspace.

Streaming errors

/v1/text-to-music and /v1/video-to-music stream application/x-ndjson. Read one JSON object per line. If an event has type: "error", stop reading and handle the included code and message.

{
  "type": "error",
  "code": "upstream_error",
  "message": "Upstream processing error. Please retry."
}

Async task errors

/v1/text-to-sfx, /v1/video-to-sfx, and /v1/audio-ducking return 202 with a task_id. Poll GET /v1/tasks/{task_id} until the task is succeeded or failed.

{
  "task_id": "9f5f2f7e-...",
  "status": "failed",
  "error": {
    "code": "upstream_error",
    "message": "Upstream processing error. Please retry."
  },
  "refunded": true
}

Retry guidance

Retry 429 and transient 502 failures with exponential backoff. When the response includes Retry-After, wait at least that many seconds before the next attempt.
Do not retry 400, 401, 403, or 422 until the request, key, permissions, or input changes.
For endpoint parameters and examples, start from the API reference.