Error Reference

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type_category",
    "param": null,
    "code": "machine_readable_code"
  }
}

{
  "error": {
    "message": "Missing or invalid credentials. Provide a valid gateway key via X-CM-API-Key / Authorization: Bearer <gateway-key>, or a valid dashboard access token via Authorization: Bearer <jwt>.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "API key has been rotated. Use the new key. Replacement key ID: key_xyz789",
    "type": "authentication_error",
    "param": null,
    "code": "key_rotated"
  }
}

{
  "error": {
    "message": "Missing provider API key. Provide your provider's API key via X-Provider-Key header, Authorization: Bearer <provider-key>, or store it via POST /gateway/admin/secrets.",
    "type": "authentication_error",
    "param": null,
    "code": "missing_provider_key"
  }
}

{
  "error": {
    "message": "Invalid JSON body",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_json"
  }
}

{
  "error": {
    "message": "Missing 'model' field in request body",
    "type": "invalid_request_error",
    "param": null,
    "code": "missing_model"
  }
}

{
  "error": {
    "message": "Unknown model 'foo-bar'. Supported prefixes: gpt-, o1-, o3-, claude-, gemini-, deepseek-",
    "type": "invalid_request_error",
    "param": null,
    "code": "unknown_model"
  }
}

{
  "error": {
    "message": "Model 'gpt-4o' is a openai model but was sent to the google endpoint. Use the correct endpoint.",
    "type": "invalid_request_error",
    "param": null,
    "code": "provider_mismatch"
  }
}

{
  "error": {
    "message": "Request body too large. Maximum size is 10485760 bytes (10 MB).",
    "type": "invalid_request_error",
    "param": null,
    "code": "request_too_large"
  }
}

{
  "error": {
    "message": "Model 'gpt-4' has been retired (shutdown: 2026-01-15). Use 'gpt-4o' instead.",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_retired"
  }
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709056860
Retry-After: 12

{
  "error": {
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit"
  }
}

{
  "error": {
    "message": "Plan limit exceeded: free tier allows 100 requests per day",
    "type": "insufficient_quota",
    "param": null,
    "code": "plan_limit_exceeded"
  }
}

{
  "error": {
    "message": "Estimated cost $3.50 exceeds per-request limit $2.00",
    "type": "permission_error",
    "param": null,
    "code": "cost_limit"
  }
}

{
  "error": {
    "message": "Daily budget exhausted: $24.50 spent + $0.52 estimated > $25.00 limit",
    "type": "permission_error",
    "param": null,
    "code": "daily_budget"
  }
}

{
  "error": {
    "message": "Monthly budget exhausted: $248.00 spent + $2.10 estimated > $250.00 limit",
    "type": "permission_error",
    "param": null,
    "code": "monthly_budget"
  }
}

{
  "error": {
    "message": "PII detected in request: credit card number found in message content",
    "type": "permission_error",
    "param": null,
    "code": "pii_detected"
  }
}

{
  "error": {
    "message": "Model 'gpt-4o' is not in the allowed model list for this organization",
    "type": "permission_error",
    "param": null,
    "code": "model_not_allowed"
  }
}

{
  "error": {
    "message": "Request requires human approval: Estimated cost $12.50 exceeds HITL threshold $10.00",
    "type": "permission_error",
    "param": null,
    "code": "needs_approval"
  }
}

HTTP/1.1 202 Accepted
X-CM-Approval-ID: apr_abc123def456
Retry-After: 30

{
  "status": "pending_approval",
  "approval_id": "apr_abc123def456",
  "retry_after_seconds": 30,
  "message": "Request requires human approval: Estimated cost $12.50 exceeds HITL threshold $10.00",
  "estimated_cost": 12.50,
  "model": "gpt-4o"
}

{
  "error": {
    "message": "Google Gemini API error: Invalid API key provided",
    "type": "upstream_error",
    "param": null,
    "code": "upstream_401"
  }
}

{
  "error": {
    "message": "Google Gemini API timed out",
    "type": "timeout_error",
    "param": null,
    "code": "timeout"
  }
}

{
  "error": {
    "message": "Failed to connect to Google Gemini API",
    "type": "connection_error",
    "param": null,
    "code": "connection_error"
  }
}

{
  "error": {
    "message": "Google Gemini is temporarily unavailable (circuit breaker open)",
    "type": "service_unavailable",
    "param": null,
    "code": "circuit_breaker_open"
  }
}

{
  "error": {
    "message": "Internal gateway error",
    "type": "gateway_error",
    "param": null,
    "code": "internal_error"
  }
}