AyaSpeech LogoBeta

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

CodeMeaningWhat to do
200SuccessRequest completed.
400Bad RequestFix the request (e.g. unsupported voice or source_lang). Don't retry as-is.
401UnauthorizedMissing or invalid x-api-token. Check the key.
403ForbiddenThe key or account can't use this right now; see the error code below. Don't retry.
404Not FoundCheck the endpoint path (e.g. an unknown job ID).
413Payload Too LargeAudio or text exceeds the limit for your plan. Send less per request.
422Validation ErrorA required field is missing or has the wrong type. The message names the field.
429Too Many RequestsA rate limit, cap or contract allocation was hit; see the error code below.
500Internal Server ErrorRetry with backoff. Contact support if it persists.
503Service BusyAll capacity is in use. Wait for the Retry-After header, then retry.
504TimeoutThe model took too long. Retry once; send shorter input if it repeats.

Error Codes

error.codeStatusMeaningWhat to do
UNAUTHORIZED401No valid API key was sent.Send x-api-token with an active key.
FORBIDDEN403Email not verified, or the key isn't active yet.Verify your email / activate the key in the dashboard.
TOKEN_REVOKED403This key was revoked (by you, or by AyaData with a reason in the message).Use another key or create a new one.
ACCOUNT_SUSPENDED403AyaData suspended API access for the account. The message gives the reason.Contact support@ayadata.ai.
CONTRACT_NOT_STARTED403Custom plan: the contract's start date hasn't arrived.Wait for the start date, or contact support.
CONTRACT_ENDED403Custom plan: the contract's end date has passed.Contact support@ayadata.ai to renew.
CONTRACT_MISSING403Custom plan without an active contract.Contact support@ayadata.ai.
SERVICE_NOT_IN_CONTRACT403Custom 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_EXCEEDED429Per-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_EXHAUSTED429Custom 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_LIMIT429Custom plan: the limit for the current 30-day period is reached.Wait for the reset date in the message, or contact support.
INVALID_INPUT400 / 422The request body or parameters are invalid.Fix the request.
INPUT_TOO_LARGE413Upload or text over the size limit.Send less per request, or use async jobs for long audio.
MODEL_UNAVAILABLE503At capacity, or a model is still loading.Retry after the Retry-After header.
TIMEOUT504Inference didn't finish in time.Retry once, then shorten the input.
SERVER_ERROR500Unexpected 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()