Copy page

Docs

Errors And Limits

Errors And Limits

Soynade returns structured errors with a stable status code and request id when available. Keep the request id when contacting support or investigating logs.

Error Shape

Code
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [],
    "request_id": "dd70d387-7375-409d-80ff-56f79125fec4"
  }
}

Some validation responses may use a detail field. Treat both shapes as possible API error responses. For diagnostics, record only the HTTP status, stable error code, and request ID. Do not log complete response or request bodies, authentication headers, prompts, audio, or external URLs.

Status Codes

Status	Meaning	Typical fix
200	Synchronous request completed.	Read the response body.
202	Job or batch accepted.	Poll status or wait for webhook.
400	Request metadata or content is invalid.	Check the request headers and body.
401	Missing or invalid API key.	Send Authorization: Bearer <key>.
402	Billing access blocked or credits exhausted.	Add credits in the dashboard.
403	The request is not authorized, or current voice-policy acceptance is missing.	Check access; for VOICE_POLICY_ACCEPTANCE_REQUIRED, ask the workspace owner to accept the displayed policy in Console.
413	The request body exceeds the documented limit.	Reduce the request body or use the appropriate upload or hosted-URL workflow.
415	Content-Type is missing or unsupported, or Content-Encoding is not identity.	Use one documented media type and send an uncompressed HTTP body.
422	Validation failed.	Check fields, types, language codes, Content-Type, and the required voice-rights attestation when reference audio is present.
429	A rate, workload, or capacity limit was reached.	Retry with backoff or reduce concurrency.
502	The request could not be completed.	Retry with backoff or use an async endpoint.
503	The service is temporarily unavailable or its usage limits are not ready.	Retry transient failures; contact support if the error persists.
504	Synchronous inference timed out.	Use the async job endpoint.

JSON Content Type

If you send JSON, include:

Code
Content-Type: application/json

Without this header, clients and playground tools may send the body as raw bytes or plain text. Body-bearing public operations reject a missing or unsupported media type with 415 UNSUPPORTED_MEDIA_TYPE.

Request Body Limits

Soynade enforces the request limits below. The numbers are decimal bytes, not MiB. Parameters such as JSON charset and the multipart boundary are allowed on the listed base media type.

Operations	Supported media type	Maximum request body
POST /v1/text-to-speech, POST /v1/text-to-speech/jobs	application/json, multipart/form-data	68,000,000 bytes
POST /v1/audio/transcriptions, POST /v1/audio/transcriptions/jobs	application/json, multipart/form-data	68,000,000 bytes
POST /v1/audio/translations, POST /v1/audio/translations/jobs	application/json, multipart/form-data	68,000,000 bytes
POST /v1/translations, POST /v1/translations/jobs	application/json	2,000,000 bytes
POST /v1/batches	application/json	256,000,000 bytes
POST /v1/batches/upload	multipart/form-data	18,000,000 bytes
POST /openai/v1/chat/completions	application/json	70,000,000 bytes

The limits apply to the complete HTTP request body. Uploaded or decoded audio is limited to 50,000,000 bytes. Batch JSONL files are limited to 16,000,000 bytes. Chat audio sources share a 50,000,000-byte decoded-audio limit within the 70,000,000-byte JSON request limit.

Use one supported Content-Type from the table. HTTP body compression is not supported. Requests above the applicable limit return 413; when the size is not known in advance, rejection may occur while the upload is in progress.

Voice-Rights Validation

When text-to-speech reference audio is present, Soynade requires voice_rights_attested to be true and voice_rights_basis to be self or authorized. This applies to synchronous, asynchronous, batch, and JSONL batch requests. Missing, false, or invalid values return 422 before synthesis. See Voice Rights and Safety. A structurally valid request returns 403 with detail.code: "VOICE_POLICY_ACCEPTANCE_REQUIRED" when the workspace does not have a current owner acceptance.

Retry Guidance

Use exponential backoff for 429, 502, 503, and 504 responses.

Do not blindly retry 400, 401, 402, 403, or 422; those usually require a request, key, or billing change.

For operations that create jobs or charge usage, send an idempotency key when the endpoint supports it:

Code
Idempotency-Key: request-2026-05-31-001

Usage And Limits

Paid burst and rolling-daily requests are counted once per workspace. Every API key and project in that workspace shares the same two buckets; creating another credential or project does not add capacity. The dashboard still shows usage by workspace, project, endpoint, and key for attribution.

Custom and Enterprise limits become active after configuration is complete. Until then, affected requests may return 503. Soynade has no unlimited mode.

Your effective limits can include:

1. Burst rate limits per minute.
2. Daily request quota.
3. Prepaid credit balance.
4. Workload limits for long-running or high-volume requests.

Use batch and async job endpoints for heavy workloads so client connections do not remain open while inference is running.

GET /health is a public liveness check and does not consume customer quota. GET /openai/v1/models requires an API key and does not consume purchased burst or daily capacity.