Error Codes

Complete reference for API errors, status codes, and how to handle them gracefully in your applications.

Error Response Format

All API errors return a consistent JSON structure:

Response Body

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

Quick Reference

Status Type Description
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Rate Limited Too many requests
500 Server Error Internal server error
503 Service Unavailable API temporarily overloaded

Client Errors (4xx)

400 Bad Request

The request was malformed or contained invalid parameters.

Common causes:

  • Invalid JSON in request body
  • Missing required parameters
  • Invalid parameter values or types
  • Exceeded max token limit

✅ Solution

Check the error message for the specific parameter that's invalid. Validate your request body against the API documentation.

401 Unauthorized

Authentication failed. The API key is missing, invalid, or expired.

Common causes:

  • Missing Authorization header
  • Invalid API key format
  • API key has been revoked
  • Using a key from the wrong organization

✅ Solution

Verify your API key in the dashboard. Ensure it's passed correctly in the Authorization header as "Bearer sk-..."

403 Forbidden

Your API key doesn't have permission to access this resource.

Common causes:

  • Accessing a model not available on your plan
  • API key lacks required scope
  • Geographic restrictions
  • Account suspended

✅ Solution

Check your account status and plan limits in the dashboard. Ensure your API key has the required permissions.

429 Rate Limited

You've exceeded your rate limit. Too many requests or tokens in a short period.

Common causes:

  • Exceeded requests per minute (RPM)
  • Exceeded tokens per minute (TPM)
  • Exceeded daily request quota

✅ Solution

Implement exponential backoff and retry. Check the Retry-After header. Consider upgrading your plan for higher limits.

Server Errors (5xx)

500 Internal Server Error

An unexpected error occurred on our servers. This is not your fault.

✅ Solution

Retry the request after a short delay. If the issue persists, check our status page or contact support.

503 Service Unavailable

The API is temporarily overloaded or under maintenance.

✅ Solution

Wait a few minutes and retry. Check the status page for ongoing incidents.

Handling Errors in Code

Python - Error Handling
from mythicdot import MythicDot
from mythicdot import (
    APIError,
    AuthenticationError,
    RateLimitError,
    BadRequestError
)

client = MythicDot()

try:
    response = client.chat.completions.create(
        model="mythic-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AuthenticationError:
    print("Invalid API key. Check your credentials.")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except BadRequestError as e:
    print(f"Bad request: {e.message}")
except APIError as e:
    print(f"API error: {e.status_code} - {e.message}")