Overview Even the best APIs return errors when something needs your attention—like a missing key or a typo in your request. Knowing how to interpret and handle these responses helps you build resilient, user-friendly applications.
Why care?
Proper error handling means less downtime, better user experience, and easier debugging.Most errors are easy to fix once you know what they mean. This page shows you how.
Example Error Response { "error" : { "message" : "Invalid or missing API key" , "type" : "error" , "code" : 401 , "tip" : "<tip>" , "trace_id" : "<trace_id>" } }
Quick Start How to catch and handle errors in your code: import OpenAI from 'openai' const openai = new OpenAI ({ apiKey: process . env . Routeway_API_KEY , baseURL: 'https://api.routeway.ai/v1' , }) try { const response = await openai . chat . completions . create ({ model: 'gpt-4o-mini' , messages: [{ role: 'user' , content: 'Hello' }] }) console . log ( response ) } catch ( error ) { // Handle API error console . error ( 'API Error:' , error . response ?. data || error . message ) }
import os from openai import OpenAI, OpenAIError client = OpenAI( api_key = os.getenv( "Routeway_API_KEY" ), base_url = "https://api.routeway.ai/v1" ) try : response = client.chat.completions.create( model = "gpt-4o-mini" , messages = [{ "role" : "user" , "content" : "Hello" }] ) print (response) except OpenAIError as e: print ( "API Error:" , e)
curl https://api.routeway.ai/v1/chat/completions \ -H "Authorization: Bearer $Routeway_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}] }'
Common Pitfalls
Missing API Key Double-check your Routeway_API_KEY is set and included in every request.
Rate Limits Too many requests? You may hit a 429 error. Add retry logic and check your usage.
Wrong Endpoint A 404 error usually means a typo in your URL or using the wrong HTTP method.
Model Support Some models don’t support function calling. Check model capabilities before using advanced features.
Deep Dive: Error Types & Solutions How to Read an Error Every error response includes:
message: Human-readable explanationtype: Error categorycode: Numeric or string code
Error Code Reference { "error" : { "message" : "Invalid or missing API key" , "type" : "error" , "code" : 401 } }
What it means: Your API key is missing, invalid, or expired.
How to fix:
Set the Routeway_API_KEY environment variable.
Include it in your request headers.
Generate a new key if needed.
What it means: Cloudflare blocked your request (suspicious or abusive behavior detected).
How to fix: { "error" : { "message" : "You have used up your free quota. Choose a paid model to continue without interruption" , "type" : "error" , "code" : 429 } }
What it means: You’ve exceeded your free rate limit.
How to fix:
Reduce request frequency.
Add retry logic with exponential backoff.
Upgrade to a paid model for higher limits.
Common causes:
Missing or empty content fields
Invalid role value
Unsupported function calling
Malformed payload
How to fix:
Check all required fields are present and valid.
Use only supported models and features.
See detailed examples below.
{ "error" : { "message" : "Empty or missing content" , "type" : "error" , "code" : 400 } }
Fix: Ensure every message has a non-empty content string.{ "error" : { "message" : "Function calling is not supported for model 'model-name'" , "type" : "error" , "code" : 400 } }
Fix: Use a model that supports function calling, or remove the functions/tools field.{ "error" : { "message" : "Invalid value for the role field" , "type" : "error" , "code" : 400 } }
Fix: Valid roles are "user", "assistant", "system", "tool".What it means: The endpoint does not exist, or the resource is missing.
How to fix:
Double-check the URL and HTTP method.
Make sure the resource exists.
Refer to the API docs for valid endpoints.
What it means: Something went wrong on the server.
How to fix:
Retry after a short delay.
If it persists, contact support with request details.
What it means: The last message in the messages array is not from the user.
How to fix:
Ensure the final message in the array has "role": "user".
Troubleshooting
Read the Error Message
The error message usually tells you exactly what’s wrong.
Check Your Request
Validate your API key, endpoint, and payload structure.
Consult the Reference
Look up the error code above for a solution.
Reference: All Error Codes Code Meaning Typical Fix 400 Bad Request Check required fields, payload structure 401 Unauthorized Set or refresh your API key 403 Forbidden Slow down, contact support if blocked 404 Not Found Check endpoint and resource existence 422 Unprocessable Entity Last message must be from user 429 Too Many Requests Reduce frequency, upgrade plan 500 Internal Server Error Retry, contact support