Error Handling - Routeway Docs

Routeway uses standard HTTP response codes to indicate the success or failure of an API request. Error responses contain a detailed JSON body that mirrors the OpenAI error schema, making it easy to parse errors programmatically.

Error Response Schema

All API errors return a standard JSON object containing an error payload:

{
  "error": {
    "message": "Invalid or missing API key",
    "type": "invalid_request_error",
    "code": 401,
    "tip": "Ensure your API key is correctly passed in the Authorization header: Bearer <KEY>",
    "trace_id": "req_01j0x7p6..."
  }
}

Fields

Field	Type	Description
`message`	`string`	A human-readable description of the error.
`type`	`string`	The category of error (e.g., `invalid_request_error`, `rate_limit_error`, `api_error`).
`code`	`integer/string`	The HTTP status code or a custom error code.
`tip`	`string`	An optional helpful suggestion to quickly resolve the error.
`trace_id`	`string`	A unique identifier for the request, useful when contacting support.

HTTP Status Codes

Status Code	Error Type	Description
400	`invalid_request_error`	Bad Request - Invalid JSON body, missing required parameters, or invalid parameters.
401	`authentication_error`	Unauthorized - Missing or incorrect API key, or the key has been revoked.
403	`permission_error`	Forbidden - The key lacks permissions for the requested model or endpoint.
404	`invalid_request_error`	Not Found - The requested endpoint does not exist.
422	`invalid_request_error`	Unprocessable Entity - Schema validation failed, or the input tokens exceeded the model’s limit.
429	`rate_limit_error`	Too Many Requests - You have exceeded your tier rate limits or custom key limits.
500	`api_error`	Internal Server Error - An unexpected error occurred on Routeway’s servers.
502	`provider_error`	Bad Gateway - The downstream AI provider (e.g., Anthropic, DeepSeek) returned an error or timed out.

Catching Errors in Code

Since Routeway uses OpenAI-compatible responses, the official OpenAI SDKs will automatically parse and throw structured exceptions.

Node.js
Python

const { OpenAI } = require("openai");

const client = new OpenAI({
  base_url: "https://api.routeway.ai/v1",
  api_key: process.env.ROUTEWAY_API_KEY,
});

async function run() {
  try {
    const response = await client.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: "Hello!" }],
    });
  } catch (error) {
    if (error instanceof OpenAI.APIError) {
      console.error(`Status: ${error.status}`); // e.g., 401
      console.error(`Message: ${error.message}`);
      console.error(`Type: ${error.type}`);
    } else {
      console.error("Non-API Error:", error);
    }
  }
}

run();

import os
from openai import OpenAI, APIError

client = OpenAI(
    base_url="https://api.routeway.ai/v1",
    api_key=os.getenv("ROUTEWAY_API_KEY")
)

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except APIError as e:
    print(f"Status: {e.status_code}") # e.g., 401
    print(f"Message: {e.message}")
    print(f"Type: {e.code}")
except Exception as e:
    print(f"Non-API Error: {e}")