Error Handling

In this guide, we'll explain what happens when something goes wrong while you work with the Martian API. Understanding error responses will help you debug issues and build robust integrations.

You can tell if your request was successful by checking the HTTP status code in the response. If a response is unsuccessful, you can use the error message and details to understand what went wrong.

HTTP Status Codes

The Martian API uses standard HTTP status codes to indicate the success or failure of requests.

Error Response Format

When an error occurs, the Martian API returns a JSON response with error details:

OpenAI-Compatible Format

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic-Compatible Format

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Common Error Types

Authentication Errors

Error Code: 401 Unauthorized

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Common causes:

• Missing Authorization header
• Incorrect API key format
• Revoked or expired API key

Solution: Verify your API key in the Martian Dashboard and ensure it's correctly formatted in the Authorization: Bearer <API_KEY> header.

Insufficient Credits

Error Code: 403 Forbidden

{
  "error": {
    "message": "Insufficient credits. Please add credits to your account.",
    "type": "insufficient_quota",
    "code": "insufficient_credits"
  }
}

Solution: Add credits to your account through the Martian Dashboard.

Invalid Model

Error Code: 404 Not Found or 400 Bad Request

{
  "error": {
    "message": "The model 'openai/gpt-99' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Common causes:

• Typo in model name
• Model doesn't exist
• Incorrect provider prefix

Solution: Check the Available Models page for the correct model name. Model names must include the provider prefix (e.g., openai/gpt-4.1-nano).

Invalid Parameters

Error Code: 400 Bad Request

{
  "error": {
    "message": "max_tokens must be a positive integer",
    "type": "invalid_request_error",
    "param": "max_tokens",
    "code": "invalid_parameter"
  }
}

Common causes:

• Missing required parameters
• Invalid parameter types
• Out-of-range values

Solution: Review the API Endpoints documentation to ensure all parameters are correctly formatted.

Rate Limiting

Error Code: 429 Too Many Requests

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Solution: Implement exponential backoff and respect the Retry-After header. See the retry logic example below.

Provider Errors

Error Code: 503 Service Unavailable

{
  "error": {
    "message": "The upstream provider is temporarily unavailable",
    "type": "api_error",
    "code": "provider_unavailable"
  }
}

Solution: Retry your request after a delay. Consider using the :cheap routing suffix for automatic failover to alternative providers.

Error Handling Best Practices

Retry Logic with Exponential Backoff

from tenacity import retry, stop_after_attempt, wait_exponential
import openai

client = openai.OpenAI(
    base_url="https://api.withmartian.com/v1",
    api_key=MARTIAN_API_KEY
)

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def make_request_with_retry(model, messages):
    try:
        return client.chat.completions.create(
            model=model,
            messages=messages
        )
    except openai.RateLimitError as e:
        print(f"Rate limit hit: {e}")
        raise
    except openai.APIError as e:
        print(f"API error: {e}")
        raise

# Usage
response = make_request_with_retry(
    model="openai/gpt-4.1-nano",
    messages=[{"role": "user", "content": "Hello!"}]
)

Comprehensive Error Handling

import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.withmartian.com/v1",
    api_key=MARTIAN_API_KEY
)

try:
    response = client.chat.completions.create(
        model="openai/gpt-4.1-nano",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)
    
except openai.AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Check your API key
    
except openai.RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    # Implement backoff and retry
    
except openai.BadRequestError as e:
    print(f"Invalid request: {e}")
    # Check your parameters
    
except openai.APIError as e:
    print(f"API error: {e}")
    # Retry or contact support
    
except Exception as e:
    print(f"Unexpected error: {e}")

If you encounter persistent errors or need assistance:

1. Check the documentation: Review the API Reference and Examples
2. Monitor your usage: Check the Martian Dashboard for quota and error logs
3. Contact support: Reach out via Discord or the dashboard