Errors

Every error from the gateway is an RFC 9457 problem response: a JSON body served as application/problem+json; charset=utf-8, with the HTTP status repeated in the body’s status field. Successful responses are ordinary application/json.

Problem format

A problem response has the following fields:

Field	Type	Description
`type`	string	Always `about:blank`.
`title`	string	The HTTP reason phrase for the status, such as `Bad Request`.
`status`	integer	The HTTP status code.
`code`	string	The machine-readable reason. Use this field, not `detail`, to decide how to handle the error.
`detail`	string	A human-readable explanation. For `invalid_request` it carries the model’s own message. Absent on `404`, `405`, and `500`.

The following example shows a 403 response:

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "code": "model_not_enabled",
  "detail": "This model does not exist or is not enabled for this organization"
}

Every response also carries an x-request-id header. Include it when you contact support about a failed request.

Error codes

The gateway returns the following status codes and error codes:

Status	Code	Title	When it happens
`400`	`invalid_body`	Bad Request	The body isn’t valid JSON, isn’t a JSON object, arrived without a JSON `Content-Type` header, or fails the endpoint’s validation. `detail` names the problem.
`400`	`invalid_request`	Bad Request	The request passed the gateway’s validation but the model rejected it. `detail` is the model’s message, for example that an input exceeds the maximum context length.
`401`	`invalid_api_key`	Unauthorized	The `Authorization` header is missing or isn’t a bearer token, or the key is malformed or doesn’t match a live key.
`401`	`api_key_revoked`	Unauthorized	Someone revoked or deleted the key in the Fourier Platform console.
`401`	`api_key_expired`	Unauthorized	The key’s expiration date has passed.
`401`	`project_archived`	Unauthorized	The project the key belongs to is archived or deleted.
`401`	`organization_deleted`	Unauthorized	The key’s organization no longer exists.
`403`	`product_not_enabled`	Forbidden	Your organization doesn’t have access to this endpoint. Contact Fourier Health to request access.
`403`	`model_not_enabled`	Forbidden	Your organization doesn’t have access to the requested `model`, or no such model exists. Contact Fourier Health to request access.
`404`	`not_found`	Not Found	The gateway doesn’t serve the path.
`405`	`method_not_allowed`	Method Not Allowed	The path doesn’t support the method. The `allow` header lists the methods it does support.
`413`	`payload_too_large`	Content Too Large	The body is over 1 MiB (1,048,576 bytes).
`429`	`rate_limited`	Too Many Requests	The organization is over its requests-per-minute limit for the model. `retry-after` says how many seconds to wait. See Rate limits.
`500`	`internal_error`	Internal Server Error	The gateway failed unexpectedly. Retry, and report the `x-request-id` if the error persists.
`502`	`upstream_error`	Bad Gateway	The model responded with a server error or an unreadable response.
`503`	`product_unavailable`	Service Unavailable	The gateway couldn’t reach the model, for example during a model deployment. `retry-after` is 30 seconds.
`504`	`upstream_timeout`	Gateway Timeout	The model didn’t respond within 30 seconds.

Handle errors

Decide how to handle an error from code, not from status or detail.
Don’t retry 400, 401, 403, or 413. Fix the request or the key first.
Retry 429, 500, 502, 503, and 504 with backoff, and wait retry-after seconds when the header is present. The openai SDKs retry these by default; see Rate limits.
Log the x-request-id header with every failure.