Errors

All error responses the API can return, with their exact payloads.

Invalid JSON

{
  "error": "Invalid JSON body"
}

Missing Messages

{
  "error": {
    "message": "`messages` array is required"
  }
}

For router endpoints, the message can be:

{
  "error": {
    "message": "`messages` array or `prompt` is required"
  }
}

Invalid API Key

{
  "error": {
    "message": "Invalid or missing API key.",
    "type": "auth_error",
    "code": "invalid_api_key"
  }
}

Pro Model Access Denied

This check still exists for pro-only Puter model ids:

{
  "error": {
    "message": "Model 'gpt-5.5' is a Pro tier model, please upgrade.",
    "type": "permission_error",
    "code": "model_access_denied",
    "required_tier": "pro",
    "model": "gpt-5.5"
  }
}

Note

Because all chat calls are routed and NVIDIA is first, this mainly matters when the effective selected/fallback model matches the pro-only rules.

Upstream Error

If the final provider returns an error:

{
  "error": {
    "message": "Upstream API error"
  }
}

All Providers Failed

If every provider in the waterfall (NVIDIA, Zen, Puter) fails or times out, the API returns:

{
  "error": {
    "message": "All upstream providers failed or timed out."
  }
}

Note

This is usually a transient upstream outage — retry the request after a short wait.

Empty Response

If all retry paths return empty content:

{
  "error": {
    "message": "The selected model returned an empty response.",
    "type": "upstream_empty_response",
    "code": "no_model_response",
    "model": "selected-model-id"
  }
}