HTTP errors

Our API follows a predictable HTTP error code format:

400 - Invalid request: there was an issue with the format or content of your request.
401 - Unauthorized: there's an issue with your API key.
403 - Forbidden: your API key does not have permission to use the specified resource.
404 - Not found: the requested resource was not found.
409 - Conflict: Resource already exists on the path.
429 - Your account has hit a rate limit.
500 - An unexpected error has occurred.
502 - Bad Gateway: The API is temporarily unavailable.
503 - The API is temporarily unavailable.

When receiving a streaming response via SSE, it's possible that an error can occur after returning a 200 response, in which case error handling wouldn't follow these standard mechanisms.

Error shapes

Errors are always returned as JSON, with a top-level error object that always includes a type and message value. For example:

Error type	Required	Description
error	Yes	The top-level error object.
type	Yes	A string representing the error type.
code	Yes	A string representing the detailed error code.
message	Yes	A string representing the error message.

{  
  "error": {  
    "type": "bad_request",
    "code": "invalid_argument",
    "message": "Invalid 'temperature': decimal above maximum value. "  
  }  
}

List of possible error codes

Below is a list of all the possible error code that the gateway can return. The Retryable column describes whether the client can attempt the same request again and expect a successful response.

Authentication

Code	Retryable	Description
`missing_api_key`	No	Client did not provide an API key for a secured endpoint.
`invalid_api_key`	No	Client provided an API key but it was malformed or otherwise invalid for the API.
`unauthorized`	No	Client was authenticated but lacks permission for target resource.

Client errors

Code	Retryable	Description
`rate_limit_exceeded`	Yes*	The client has exceeded their allocated quota and must wait before making new requests.
`invalid_request`	No	Request from client could not be parsed due to size, format or content type issues.
`invalid_argument`	No	Request from client is missing fields or contains fields that is not compatible with the called API or model.
`not_found`	No	Requested endpoint does not exist.
`unknown_model`	No	Client provided model name could not be found.
`invalid_content_media`	No	Request attached media content could not be processed.
`unavailable_content_media`	No	Remote media content referenced by request could not be accessed.
`unsafe_content`	No	The request was denied during safety pre-processing of content.
`unknown_app`	No	Failed to find a GIP app with the request provided ID.
`invalid_app`	No	The requested GIP app is invalid and cannot be used.
`unsupported_interface`	No	The requested inference API (e.g. chat) is not available for target model.

^* Retryable after backing off for rate limit quota to reset.

Gateway internal errors

Code	Retryable	Description
`unknown_workspace`	No	The workspace of the provided API key could not be retrieved.
`failed_request`	No	An unexpected error was encountered when building the model request or parsing the response.
`internal_error`	No	Unexpected internal gateway error.

Model server errors

Code	Retryable	Description
`model_server_error`	Yes	Model responded with a server error.
`model_overloaded`	Yes	Model is currently overloaded and could not handle the request.
`model_unavailable`	No	The gateway could not reach the model due to network, configuration or other issues.
`model_timeout`	Yes	Request to model server timed out.
`stream_error`	Yes	An error was encountered while streaming a response from the model to the client.
`stream_terminated`	Yes	The model stream was unexpectedly terminated from the model's side.