DocsDeployment APIError Codes

Error Codes

Complete list of error codes and troubleshooting guidance.

Navigation

Error Codes

The Deployment API uses standard HTTP status codes and returns errors in a consistent JSON format compatible with the OpenAI error schema.

Error Response Format

{
  "error": {
    "message": "Human-readable description of the error.",
    "type": "error_type",
    "code": "error_code",
    "param": null
  }
}

Error Types

HTTP Status	Type	Code	Description
400	`invalid_request_error`	`invalid_json`	Request body is not valid JSON
400	`invalid_request_error`	`missing_required_parameter`	A required field is missing (e.g., messages, prompt, input)
400	`invalid_request_error`	`model_not_found`	The requested model is not available on this deployment
401	`invalid_request_error`	`missing_api_key`	No Authorization header or Bearer token provided
401	`authentication_error`	`invalid_api_key`	API key is invalid, revoked, or expired
429	`rate_limit_error`	`rate_limit_exceeded`	Too many requests — wait and retry
500	`api_error`	`internal_error`	Internal server error during request processing
502	`api_error`	`backend_unavailable`	Could not reach the deployment backend (may be starting up)
503	`invalid_request_error`	`deployment_not_running`	Deployment is stopped or in a non-running state

Handling Errors

import openai

try:
    response = client.chat.completions.create(
        model="llama-4-scout",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.AuthenticationError:
    print("Invalid API key. Check your mcy_live_* key.")
except openai.RateLimitError:
    print("Rate limited. Implement exponential backoff.")
except openai.APIConnectionError:
    print("Backend unavailable. Deployment may be starting.")
except openai.APIError as e:
    print(f"API error: {e.message}")

← Previous

Rate Limits

Migration Guide