Error Handling
The API uses standard HTTP status codes. Every error response has the same JSON shape: a stable machine-readable code to branch on, and a human-readable message to log or show.
Error Response Format
{
"error": {
"code": "CONTRACT_ALLOCATION_EXHAUSTED",
"message": "Contract allocation for Translation (MT) used up (2,987 characters of 3,000 characters; this request needs 57 characters). Contact support@ayadata.ai to top up."
}
}Branch on error.code; message wording may change. Some responses also carry headers you should honour, such as Retry-After (seconds to wait).
Status Codes
| Code | Meaning | What to do |
|---|---|---|
| 200 | Success | Request completed. |
| 400 | Bad Request | Fix the request (e.g. unsupported voice or source_lang). Don't retry as-is. |
| 401 | Unauthorized | Missing or invalid x-api-token. Check the key. |
| 403 | Forbidden | The key or account can't use this right now; see the error code below. Don't retry. |
| 404 | Not Found | Check the endpoint path (e.g. an unknown job ID). |
| 413 | Payload Too Large | Audio or text exceeds the limit for your plan. Send less per request. |
| 422 | Validation Error | A required field is missing or has the wrong type. The message names the field. |
| 429 | Too Many Requests | A rate limit, cap or contract allocation was hit; see the error code below. |
| 500 | Internal Server Error | Retry with backoff. Contact support if it persists. |
| 503 | Service Busy | All capacity is in use. Wait for the Retry-After header, then retry. |
| 504 | Timeout | The model took too long. Retry once; send shorter input if it repeats. |
Error Codes
| error.code | Status | Meaning | What to do |
|---|---|---|---|
| UNAUTHORIZED | 401 | No valid API key was sent. | Send x-api-token with an active key. |
| FORBIDDEN | 403 | Email not verified, or the key isn't active yet. | Verify your email / activate the key in the dashboard. |
| TOKEN_REVOKED | 403 | This key was revoked (by you, or by AyaData with a reason in the message). | Use another key or create a new one. |
| ACCOUNT_SUSPENDED | 403 | AyaData suspended API access for the account. The message gives the reason. | Contact support@ayadata.ai. |
| CONTRACT_NOT_STARTED | 403 | Custom plan: the contract's start date hasn't arrived. | Wait for the start date, or contact support. |
| CONTRACT_ENDED | 403 | Custom plan: the contract's end date has passed. | Contact support@ayadata.ai to renew. |
| CONTRACT_MISSING | 403 | Custom plan without an active contract. | Contact support@ayadata.ai. |
| SERVICE_NOT_IN_CONTRACT | 403 | Custom plan: this service (ASR, MT or TTS) isn't included. Pipelines check every step before anything runs. | Contact support to add the service. |
| RATE_LIMIT_EXCEEDED | 429 | Per-minute rate limit, daily cap or monthly volume cap reached (the message says which). | Per-minute: wait for Retry-After. Caps: wait for the reset shown in the message. |
| CONTRACT_ALLOCATION_EXHAUSTED | 429 | Custom plan: the request needs more than the allocation left for this service. | Contact support@ayadata.ai to top up. Smaller requests may still fit. |
| CONTRACT_MONTHLY_LIMIT | 429 | Custom plan: the limit for the current 30-day period is reached. | Wait for the reset date in the message, or contact support. |
| INVALID_INPUT | 400 / 422 | The request body or parameters are invalid. | Fix the request. |
| INPUT_TOO_LARGE | 413 | Upload or text over the size limit. | Send less per request, or use async jobs for long audio. |
| MODEL_UNAVAILABLE | 503 | At capacity, or a model is still loading. | Retry after the Retry-After header. |
| TIMEOUT | 504 | Inference didn't finish in time. | Retry once, then shorten the input. |
| SERVER_ERROR | 500 | Unexpected server error. | Retry with backoff; contact support if persistent. |
Retry Strategy
503 and per-minute 429: wait the number of seconds in the Retry-After header, then retry. Add a little random jitter so many callers don't retry at the same instant.
504 and 500: retry with exponential backoff (1s, 2s, 4s), at most 3 times.
Daily / monthly caps and contract codes: retrying won't help until the reset or a top-up; the message says when, or who to contact.
400, 401, 403, 404, 413, 422: don't retry. Fix the request or the account first.
import random, time, requests
def call_with_retries(url, headers, json, attempts=4):
for attempt in range(attempts):
r = requests.post(url, headers=headers, json=json, timeout=130)
if r.ok:
return r
code = r.json().get("error", {}).get("code")
retry_after = r.headers.get("Retry-After")
if r.status_code in (503, 429) and retry_after and code in ("MODEL_UNAVAILABLE", "RATE_LIMIT_EXCEEDED"):
time.sleep(int(retry_after) + random.random()) # busy / per-minute limit
elif r.status_code in (500, 504):
time.sleep(2 ** attempt) # transient
else:
r.raise_for_status() # don't retry: fix the request or account
r.raise_for_status()