Documentation

Error Codes

Comprehensive guide to MX4 Atlas API error codes and how to handle them.

Last updated on February 2, 2026

Error Response Format

All API errors follow a consistent JSON format. The error object contains an error code, message, and optional details.

json

1{
2  "error": {
3    "code": "invalid_request_error",
4    "message": "The request is not valid.",
5    "details": {
6      "field": "model",
7      "issue": "Model not found"
8    }
9  }
10}

Common Error Codes

400 - Bad Request

invalid_request_error

The request was malformed or contained invalid parameters.

Common causes: Missing required fields, invalid parameter values, malformed JSON

401 - Unauthorized

authentication_error

Authentication failed or API key is invalid.

Common causes: Invalid API key, missing Authorization header, expired key

403 - Forbidden

permission_denied

Access to the requested resource is forbidden.

Common causes: Insufficient permissions, region restrictions, sovereignty violations

404 - Not Found

not_found_error

The requested resource was not found.

Common causes: Invalid endpoint URL, model not available, resource deleted

429 - Too Many Requests

rate_limit_error

Rate limit exceeded. See Rate Limits for details.

Common causes: Too many requests in time window, token limit exceeded

500 - Internal Server Error

internal_error

An unexpected error occurred on our servers.

Common causes: Service issues, temporary outages, unexpected conditions

503 - Service Unavailable

service_unavailable

The service is temporarily unavailable.

Common causes: Maintenance, high load, regional outages

Error Response Examples

Here are complete error response examples for common scenarios:

Authentication Error

json

1HTTP/1.1 401 Unauthorized
2Content-Type: application/json
3
4{
5  "error": {
6    "code": "authentication_error",
7    "message": "Invalid API key provided",
8    "details": {
9      "reason": "api_key_invalid"
10    }
11  }
12}

Bad Request Error

json

1HTTP/1.1 400 Bad Request
2Content-Type: application/json
3
4{
5  "error": {
6    "code": "invalid_request_error",
7    "message": "Missing required field: model",
8    "details": {
9      "field": "model",
10      "issue": "required_field_missing"
11    }
12  }
13}

Error Handling Best Practices

Implement robust error handling in your applications to gracefully manage API failures.

error_handling.pypython

1import openai
2from openai import OpenAI
3
4client = OpenAI(
5    api_key="mx4-sk-...",
6    base_url="https://api.mx4.ai/v1"
7)
8
9def handle_api_errors():
10    try:
11        response = client.chat.completions.create(
12            model="mx4-atlas-core",
13            messages=[{"role": "user", "content": "مرحبا"}]
14        )
15        return response
16    except openai.AuthenticationError:
17        print("Authentication failed. Check your API key.")
18        return None
19    except openai.RateLimitError:
20        print("Rate limit exceeded. Please wait before retrying.")
21        return None
22    except openai.BadRequestError as e:
23        print(f"Bad request: {e}")
24        return None
25    except openai.InternalServerError:
26        print("Internal server error. Please try again later.")
27        return None
28    except Exception as e:
29        print(f"Unexpected error: {e}")
30        return None

Advanced Error Handling Pattern

advanced_error_handling.pypython

1import openai
2import time
3import logging
4
5client = openai.OpenAI(api_key="mx4-sk-...")
6logger = logging.getLogger(__name__)
7
8async def make_api_call_with_logging(messages, max_retries=3):
9    for attempt in range(max_retries):
10        try:
11            response = client.chat.completions.create(
12                model="mx4-atlas-core",
13                messages=messages
14            )
15            logger.info(f"API call successful on attempt {attempt + 1}")
16            return response
17        
18        except openai.AuthenticationError as e:
19            logger.error(f"Authentication error: {e}")
20            raise e  # Don't retry auth errors
21        
22        except openai.RateLimitError as e:
23            if attempt == max_retries - 1:
24                logger.error(f"Rate limit exceeded after {max_retries} retries")
25                raise e
26            wait_time = 2 ** attempt
27            logger.warning(f"Rate limited. Retrying in {wait_time}s (attempt {attempt + 1})")
28            await asyncio.sleep(wait_time)
29        
30        except openai.InternalServerError as e:
31            if attempt == max_retries - 1:
32                logger.error(f"Server error after {max_retries} retries: {e}")
33                raise e
34            wait_time = 5 * (attempt + 1)
35            logger.warning(f"Server error. Retrying in {wait_time}s")
36            time.sleep(wait_time)
37        
38        except Exception as e:
39            logger.error(f"Unexpected error: {e}")
40            raise e

Error Prevention Guide

Validate Inputs

Check request parameters before sending to API to catch 400 errors early.

Secure API Keys

Store keys in environment variables, rotate regularly, never commit to version control.

Monitor Rate Limits

Check rate limit headers and implement queue systems to stay within limits.

Handle Timeouts

Set appropriate request timeouts and implement graceful fallback mechanisms.

Tip: Always check the error code and message in the response. For persistent issues, contact support with the full error details and request ID from your logs.