Errors
RFC 9457 problem+json error envelope, status codes, and error code catalog.
الأخطاء
تُعاد جميع الأخطاء بصيغة موحّدة application/problem+json وفق معيار RFC 9457، مع
رمز خطأ ومعرّف طلب لتتبّعه مع فريق الدعم.
Every ASAS error is returned as a single, consistent envelope:
application/problem+json (RFC 9457), with an ASAS code and a request_id you
can quote to support.
Error envelope
{
"type": "about:blank",
"title": "Text exceeds the maximum length",
"status": 422,
"detail": "text must be at most 500 characters",
"code": "text_too_long",
"request_id": "req_9f2c1a7b3e"
}| Field | Meaning |
|---|---|
status | HTTP status code (also on the response). |
title | Short, human-readable summary. |
detail | Specifics for this occurrence. |
code | Stable machine-readable ASAS error code — branch on this, not on title. |
request_id | Correlates the request across ASAS logs. Include it in support tickets. |
Error bodies never leak upstream hostnames, paths, or stack traces. Upstream FLITC errors are normalized into this envelope.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | Malformed request | Fix the request body / headers. |
401 | Missing or invalid API key | Check the Authorization header. |
403 | Key lacks the required scope | Grant the scope, or use a key that has it. |
404 | Resource not found | Check the id / path. |
409 | Conflict / not ready (e.g. RAG tenant provisioning) | Retry after the indicated delay. |
422 | Validation failed | Read detail; fix the field. |
429 | Rate limit or quota exceeded | Back off; see Rate limits. |
500 | Gateway error | Retry with backoff; contact support with request_id. |
502 / 504 | Upstream error / timeout | Retry with backoff. Do not auto-retry synthesis blindly. |
Common error codes
code | Status | Meaning |
|---|---|---|
unauthorized | 401 | No valid key on the request. |
insufficient_scope | 403 | Key is valid but not scoped for this endpoint. |
text_too_long | 422 | TTS text over 500 characters. |
validation_error | 422 | A field failed schema validation. |
rate_limited | 429 | Request-rate limit hit. Honor Retry-After. |
quota_exceeded | 429 | Out of credits. Top up / contact sales. |
concurrency_limit | 429 | Too many concurrent streams for your tier. |
rag_not_provisioned | 409 | RAG entitlement not yet provisioned. |
rag_resuming | 409 | RAG tenant is resuming from idle; retry after Retry-After. |
upstream_timeout | 504 | Upstream model timed out. |
Handling errors well
- Branch on
code, never ontitleordetail(those may be localized or reworded). - Respect
Retry-Afteron409/429— it tells you exactly how long to wait. - Log
request_idon every failure so support can trace it end to end.