Error handling

The Mira API uses standard HTTP status codes to indicate request success or failure. All errors are returned in a consistent JSON format with detailed information about the issue.

Error response format

JSON

{
  "detail": "The 'model' field is required."
}

HTTP status codes

400 Bad Request

The request contains invalid parameters or is missing required fields.

401 Unauthorized

The API key is invalid, expired, or missing. Make sure the Authorization header contains a valid key.

402 Payment Required

Insufficient balance. Top up your account in the dashboard.

403 Forbidden

The API key is valid but lacks permission for the requested action. Your plan may not include access to the requested Mira model.

404 Not Found

The requested endpoint does not exist. Check the URL and HTTP method.

429 Too Many Requests

Rate limit exceeded. The response includes a Retry-After header indicating the number of seconds until the next allowed request.

429 error example

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "detail": "Rate limit exceeded. Please retry after 60 seconds."
}

Always check the Retry-After header when receiving a 429 error. Do not retry without waiting the specified interval.

500 Internal Server Error

An internal server error occurred. Retry after a few seconds.

Error summary table

CodeDescriptionAction

400Bad requestFix your parameters

401UnauthorizedCheck your API key

402Payment requiredTop up your balance

403ForbiddenUpgrade your plan

404Not foundCheck the URL

429Rate limitedWait for Retry-After

500Server errorRetry the request

Retry logic

For 429, 500, and 503 errors, implement exponential backoff. Start with a short delay and increase it with each attempt.

Python

import os
import time
import requests

def call_mira_api(messages, max_retries=5):
    url = "https://api.vmira.ai/v1/chat/completions"
    headers = {
        "Authorization": f"Bearer {os.environ['MIRA_API_KEY']}",
        "Content-Type": "application/json",
    }
    payload = {"model": "mira", "messages": messages}

    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        if response.status_code in (500, 503):
            delay = min(2 ** attempt, 60)
            time.sleep(delay)
            continue

        response.raise_for_status()

    raise Exception("Max retries exceeded")

Add random jitter to the delay to avoid the "thundering herd" problem — when many clients retry simultaneously.