Error Handling

Understanding API error responses.

Pofano exposes multiple API surfaces, so error behavior is not completely uniform across every route. The most important distinction is whether you are calling a relay endpoint such as /v1/chat/completions, a provider-native endpoint such as /v1/messages, or a dashboard/account endpoint such as /api/user/billing/summary.

Relay Endpoints#

OpenAI-compatible relay routes generally return an HTTP error status together with an OpenAI-style error object:

{
  "error": {
    "message": "Your request is invalid.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Typical relay status codes include 400, 401, 403, 404, 413, 429, and 500, depending on the failure path.

Claude-Compatible Endpoints#

Anthropic-compatible routes such as POST /v1/messages return a Claude-style wrapper instead of the OpenAI wrapper:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Your request is invalid."
  }
}

These responses still use an HTTP error status, but the JSON shape differs from the OpenAI-compatible routes.

Dashboard And Account APIs#

Dashboard/account JSON endpoints such as GET /api/user/billing/summary use a different envelope:

{
  "success": false,
  "message": "invalid user"
}

These endpoints usually rely on standard 4xx or 5xx statuses together with success / message fields.

Known Compatibility Quirk#

Some model lookup routes do not use a non-200 status when a model lookup fails. For example, GET /v1/models/:model can return HTTP 200 with an OpenAI-style error object in the response body:

{
  "error": {
    "message": "The model 'missing-model' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Always inspect the response body, not only the HTTP status code, when integrating model discovery or compatibility routes.

Common Error Fields#

Common Error Codes#