Meliai API Errors: Codes, Messages, and Retry Logic

When a request cannot be completed, Meliai returns a JSON error object in the response body alongside an appropriate HTTP status code. The code field is a stable, machine-readable identifier you can match against in your application logic. The message field is human-readable and intended for logging and debugging — its wording may change between API versions. The optional details object provides structured context such as token counts or limit values.

Error Response Shape

{
  "error": {
    "code": "INFERENCE_3207",
    "message": "Input exceeds the model's context window",
    "details": { "context_length": 131072, "input_tokens": 164228 }
  }
}

Always match on code for programmatic error handling — it is stable across API versions. Treat message as a human-readable hint for logs and dashboards, not as a key to branch on.

HTTP Status Codes

Status	Meaning
200	Success
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks required scope
404	Not found — model or resource does not exist
429	Rate limit exceeded
500	Internal server error
503	Service unavailable

Common Error Codes

INFERENCE_3103 — All providers failed

HTTP status: 503All European providers available for this model and routing flavor returned errors or were unavailable at the time of the request. This is a transient condition — Meliai’s auto-failover already attempted every eligible provider before surfacing this error.Resolution: Retry the request using exponential backoff. If the error persists beyond several minutes, check the Meliai status page for active incidents. Consider using the :balanced routing flavor to maximise the pool of eligible providers.

INFERENCE_3207 — Input exceeds context window

HTTP status: 400The total number of input tokens exceeds the maximum context length supported by the requested model. The details object includes context_length (the model’s limit) and input_tokens (the size of your request).Resolution: Reduce the length of your messages, system prompt, or tool definitions, or switch to a model with a larger context window. You can retrieve the context length for any model via GET /v1/models/{id}.

AUTH_1001 — Invalid API key

HTTP status: 401The API key provided is missing, malformed, or has been revoked. Meliai API keys follow the format sk-mel-<KEY>.Resolution: Verify that:

The Authorization: Bearer sk-mel-... or x-api-key: sk-mel-... header is present on the request.
The key value is copied in full with no leading or trailing whitespace.
The key has not been revoked in the Meliai dashboard.

RATE_2001 — Rate limit exceeded

HTTP status: 429Your account or API key has exceeded its request-rate or token-rate limit for the current time window. The response may include Retry-After and X-RateLimit-Reset headers indicating when the limit resets.Resolution: Back off and retry after the indicated reset time. For sustained high-volume workloads, use the Batches API (POST /v1/batches) which is not subject to the same synchronous rate limits.

Retry Strategy

Apply exponential backoff when retrying transient errors. The following rules keep your retry logic safe and efficient:

Retry on 429 (rate limit) and INFERENCE_3103 (all providers failed).
Retry on 503 after a short delay — the service may be recovering.
Do not retry other 4xx errors. They indicate a problem with the request itself (bad parameters, invalid key, missing resource) that will not resolve on its own.
Do not retry 500 errors automatically in production without a cap — surface them for investigation.

The example below implements capped exponential backoff for rate-limit errors using the openai Python SDK:

import time
import os
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key=os.environ["MELIAI_API_KEY"],
    base_url="https://api.meliai.ai/v1",
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="<MODEL_ID>",
                messages=messages,
            )
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

For high-volume or non-latency-sensitive workloads, use the Batches API instead of retrying synchronous requests. Batch jobs are processed asynchronously and are not subject to synchronous rate limits.

Overview

Inference

Batch & Files

Models

Meliai API Errors: Codes, Messages, and Retry Logic

Error Response Shape

HTTP Status Codes

Common Error Codes

Retry Strategy

​Error Response Shape

​HTTP Status Codes

​Common Error Codes

​Retry Strategy

Error Response Shape

HTTP Status Codes

Common Error Codes

Retry Strategy