everyais
← All docs

Reference

Errors and retries

Updated

Error format

Inference APIs return errors in the OpenAI format. /v1/messages can use the Anthropic format (type: "error").

json
{
  "error": {
    "message": "Incorrect API key provided. ...",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Branch on error.code; message wording can change. param names the field that caused the error. Errors after a stream starts arrive as stream events. See streaming. The event's error.code is the same as in the table below (for example provider_unavailable or upstream_timeout). Stream events carry no Retry-After, so wait a few seconds before resending.

What to do for each status

Statustype / codeCauseRetry?
400invalid_request_error / unsupported_parameter · unsupported_value · image_input_unsupported · context_length_exceededInvalid parameter, context too long, or an option or image input the model doesn't supportNo. Fix the request
401authentication_error / missing_api_key · invalid_api_keyMissing, invalid or expired keyNo
402insufficient_quota_error / insufficient_quota · spend_limit_exceededNot enough credit, or the key's spend limitAfter adding credit or raising the limit
403permission_error / model_not_allowed · insufficient_scopeModel or scope not allowed for this keyNo
404invalid_request_error / model_not_found · job_not_foundWrong model ID, model blocked by your settings, or expired jobNo
409idempotency_*Idempotency-Key collision. See belowDepends
413invalid_request_error / request_too_largeBody over the size limitAfter making it smaller
429rate_limit_error / rate_limit_exceededPer-minute request limit exceededYes, after Retry-After
502api_error / backend_unavailable · upstream_errorThe model provider returned an errorYes, with backoff
503api_error / model_warmingThe model is startingYes, after Retry-After
503api_error / provider_unavailableEvery route for this model is briefly blocked. Your request was not runYes, after Retry-After (30 s at most)
504api_error / upstream_timeoutThe model provider did not respond in timeYes, with backoff

When a provider rejects the request, the 400 carries the provider's field and code in param and code (for example param: "reasoning_effort", code: "unsupported_value"). The field is renamed to the API you called: a Chat Completions request gets messages, not the provider wire's input. The provider's own message text is not included.

For 404 model_not_found on an ID that looks right, check the key's allowed models and your access settings.

409: when an Idempotency-Key collides

codeMeaningWhat to do
idempotency_in_progressThe same request is still runningWait. Don't resend with a new key
idempotency_key_reusedA different body was sent with the same keyUse a new key per distinct request
idempotency_response_not_replayableIt already ran, but a stream or large result can't be replayedCheck the output and your usage

503 model_warming

The model is starting. Your request was not run. Retry after Retry-After seconds. Some models take 10–20 minutes to start.

Rate limits

Each key allows 100 requests per minute by default; change it when you create or edit the key. Login, sign-up and other auth endpoints have a lower limit.

HeaderMeaning
X-RateLimit-LimitThe key's per-minute limit
X-RateLimit-RemainingRequests left in the window
X-RateLimit-ResetReset time (Unix milliseconds)
Retry-AfterSeconds to wait before retrying a 429 or 503

Retry code

The OpenAI SDK retries 429 and 5xx twice with short waits. A 503 model_warming can last minutes, so retry yourself.

python
import os
import random
import time
from openai import APIStatusError, OpenAI

client = OpenAI(
    base_url="https://api.everyais.com/v1",
    api_key=os.environ["EVERYAIS_API_KEY"],
    max_retries=0,  # we retry below
)
RETRYABLE = {429, 502, 503, 504}

def create_with_retry(attempts=5, **request):
    for attempt in range(attempts):
        try:
            return client.chat.completions.create(**request)
        except APIStatusError as error:
            if error.status_code not in RETRYABLE or attempt == attempts - 1:
                raise
            wait = float(error.response.headers.get("retry-after") or 2 ** attempt)
            time.sleep(wait + random.random())
  • Send an Idempotency-Key with automatic retries so a request doesn't run twice. See compatibility features.
  • Video submission doesn't support Idempotency-Key. If you lose the submit response, check the job status before resubmitting.

Contacting support

Include the x-request-id response header, the HTTP status and error.code.

Contact support