Skip to main content
Even the best models encounter occasional failures. This guide explains how the Gateway reports errors and how you should respond.

​
Error format

Errors are returned in a structured JSON format, providing details about the issue encountered. 
{
	"error": {
		"type": "rate_limit_exceeded",
		"message": "Too many requests in the last minute.",
		"request_id": "req_abc123",
		"provider": "openai"
	}
}
Use request_id when contacting support, as it links directly to internal logs for faster assistance.

​
Retry strategy

Generally, 4xx status codes indicate a misconfiguration on your end, such as invalid parameters, missing fields, or authentication issues. These errors should be addressed by correcting your request rather than retrying. 5xx status codes point to gateway or provider-side issues. If you encounter these repeatedly, please report them to our support team for investigation.
We will always try and return helpful error messages, but if you see something unclear, please let us know!

​
Working with providers

Sometimes errors originate upstream. We will always attempt to indicate this in the error response. The router should attempt to navigate you away from that provider if possible, should these errors keep happening.
🧠 Reminder The Examples repository includes snippets that implement all of the strategies described here.