Error Codes

Error Code Reference

When an API request fails, the response includes an HTTP status code and an error object with details about what went wrong. The following table lists all possible error codes:

Error Response Format

Error responses follow this structure:

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided.",
    "type": "error"
  }
}

Best Practices for Error Handling

Implement Retry Logic

Not all errors should be retried. Use the following guidelines:

• Retryable errors (429, 500, 503): These are transient errors that may resolve on their own. Implement automatic retry with exponential backoff.
• Non-retryable errors (400, 401, 403, 404): These indicate issues with your request or credentials. Fix the underlying problem before retrying.

Exponential Backoff Strategy

When retrying failed requests, use exponential backoff to avoid overwhelming the server:

import time
import random

def make_request_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise e

            # Exponential backoff with jitter
            delay = min(2 ** attempt + random.random(), 60)
            print(f"Request failed, retrying in {delay:.1f}s... (attempt {attempt + 1}/{max_retries})")
            time.sleep(delay)

Handle Rate Limits Gracefully

If you receive a 429 rate_limit_exceeded error:

1. Respect the retry-after header: If the response includes a Retry-After header, wait at least that long before retrying.
2. Reduce concurrency: Lower the number of parallel requests to stay within rate limits.
3. Implement request queuing: Queue requests and process them at a controlled rate.

Log Errors for Debugging

Always log error responses including the full error object, request ID (if available), and timestamp. This information is essential when contacting support for persistent issues.

Validate Requests Before Sending

Reduce 400 invalid_request errors by validating your request data before sending:

• Ensure all required fields are present.
• Verify the model name matches one of the available models (mimo-v2-pro, mimo-v2-omni, mimo-v2-tts, mimo-v2-flash).
• Check that parameter values are within acceptable ranges.
• Confirm the API Key is set and not empty.