Errors

All error responses follow the same JSON format:

{
  "error": {
    "message": "Description of what went wrong"
  }
}

HTTP status codes

Status Meaning When
400 Bad Request Invalid request parameters (missing fields, wrong types)
401 Unauthorized Missing, invalid, or expired API key / JWT token
402 Payment Required Valid authentication but insufficient credit balance
404 Not Found Requested resource does not exist (e.g., unknown model)
422 Unprocessable Entity Unsupported parameter or invalid field structure
503 Service Unavailable Upstream provider error (timeout, rate limit, connection failure)

Error types

Bad Request (400)

Returned when the request payload is invalid. The message describes the specific issue.

{
  "error": {
    "message": "field required: 'model'"
  }
}

Model modality mismatch

A 400 is also returned when a chat-completion request contains a content part (image_url, input_audio, video_url) that the target model does not support. This check runs before the request reaches the provider.

{
  "error": {
    "message": "Model 'openai/gpt-4.1-nano' does not support audio input"
  }
}

Pick a model that declares the required modality in input_modality (see Models). file (PDF) parts are exempt from this check — OpenRouter’s universal PDF parser handles them on every model.

Strict validation

All request bodies use strict validation — unknown or unsupported fields are rejected with 422. This prevents typos from being silently ignored and ensures you only use documented parameters.

Unprocessable Entity (422)

Returned when the request contains an unsupported parameter, an invalid field structure, or an unknown content type. The response includes details about which field was rejected.

{
  "detail": [
    {
      "type": "extra_forbidden",
      "loc": ["body", "logprobs"],
      "msg": "Extra inputs are not permitted",
      "input": true
    }
  ]
}

Common causes:

  • Using an unsupported parameter (e.g., top_k, modalities, audio)
  • Adding unknown fields to messages (e.g., images)
  • Using an unknown content part type value (supported types are text, image_url, input_audio, video_url, file)
  • Invalid structure for tools, response_format, or reasoning

Unauthorized (401)

Returned when the API key is missing, invalid, deactivated, or expired.

{
  "error": {
    "message": "Invalid API key"
  }
}

Payment Required (402)

Returned when your license has insufficient credits to process the request.

{
  "error": {
    "message": "Insufficient credits"
  }
}

Check your balance with GET /v1/license and contact your institution to top up.

Not Found (404)

Returned when a requested resource (e.g., a model ID) does not exist at the provider.

{
  "error": {
    "message": "Model 'nonexistent-model' not found"
  }
}

Service Unavailable (503)

Returned when the upstream provider encounters an error. The actual error details are masked for security:

{
  "error": {
    "message": "Service temporarily unavailable"
  }
}

This covers:

  • Timeouts — the provider did not respond in time
  • Rate limits — the provider is throttling requests
  • Connection errors — network issues reaching the provider
  • Authentication errors — issues with the upstream API key (not your Quantized key)
Masked messages

503 errors always return “Service temporarily unavailable” regardless of the underlying cause. This prevents leaking internal infrastructure details.

Handling errors

import httpx

response = httpx.post(
    "https://api.quantized.us/v1/chat/completions",
    headers={"Authorization": "Bearer sk-quantized-YOUR-KEY"},
    json={"model": "openai/gpt-4.1-mini", "messages": [...]},
)

if response.status_code == 200:
    data = response.json()
    print(data["choices"][0]["message"]["content"])
elif response.status_code == 402:
    print("Out of credits — contact your institution")
elif response.status_code == 422:
    details = response.json()["detail"]
    for d in details:
        print(f"Unsupported field: {'.'.join(str(x) for x in d['loc'])}")
elif response.status_code == 503:
    print("Provider unavailable — retry after a moment")
else:
    error = response.json()
    print(f"Error {response.status_code}: {error['error']['message']}")
Previous Providers Next Streaming