Error Handling

Understanding and handling GateFlow API errors.

Error Format

All errors follow a consistent format:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_category",
    "code": "specific_error_code",
    "param": "problematic_parameter",
    "doc_url": "https://gateflow.ai/docs/api-reference/errors/..."
  }
}

Error Fields

Field	Type	Description
message	string	Human-readable description
type	string	Error category
code	string	Specific error code
param	string	Parameter that caused error (if applicable)
doc_url	string	Link to documentation

Error Types

Authentication Errors

HTTP 401 - Invalid or missing credentials.

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

See Auth Errors for details.

Permission Errors

HTTP 403 - Valid credentials but insufficient permissions.

{
  "error": {
    "message": "Model 'gpt-4o' not allowed for this API key",
    "type": "permission_error",
    "code": "model_not_allowed"
  }
}

Rate Limit Errors

HTTP 429 - Too many requests.

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Headers:

Retry-After: 60
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705123516

See Rate Limit Errors for details.

Invalid Request Errors

HTTP 400 - Malformed or invalid request.

{
  "error": {
    "message": "Invalid value for 'temperature': must be between 0 and 2",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "temperature"
  }
}

Provider Errors

HTTP 502/503 - Upstream provider issues.

{
  "error": {
    "message": "Provider 'openai' is temporarily unavailable",
    "type": "provider_error",
    "code": "provider_unavailable",
    "provider": "openai"
  }
}

See Provider Errors for details.

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Internal Server Error - GateFlow issue
502	Bad Gateway - Provider unreachable
503	Service Unavailable - Temporary outage

Handling Errors

Python

from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_..."
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError as e:
    print(f"Invalid API key: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.response.headers.get('Retry-After')}")
except APIError as e:
    print(f"API error: {e.code} - {e.message}")

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.gateflow.ai/v1',
  apiKey: 'gw_prod_...',
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof OpenAI.RateLimitError) {
    console.log('Rate limited');
  } else if (error instanceof OpenAI.APIError) {
    console.log(`API error: ${error.code} - ${error.message}`);
  }
}

cURL

response=$(curl -s -w "\n%{http_code}" \
  https://api.gateflow.ai/v1/chat/completions \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}')

http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" != "200" ]; then
  echo "Error $http_code: $body"
fi

Retry Strategy

Exponential Backoff

import time
import random

def call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Exponential backoff with jitter
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Retry-After Header

except RateLimitError as e:
    retry_after = int(e.response.headers.get('Retry-After', 60))
    time.sleep(retry_after)

Retryable Errors

Error	Retry?	Strategy
429 Rate Limit	Yes	Wait for Retry-After
500 Internal Error	Yes	Exponential backoff
502 Bad Gateway	Yes	Exponential backoff
503 Unavailable	Yes	Exponential backoff
400 Bad Request	No	Fix request
401 Unauthorized	No	Fix credentials
403 Forbidden	No	Check permissions

Error Codes Reference

Authentication (authentication_error)

Code	Description
invalid_api_key	API key doesn't exist
expired_api_key	API key has expired
revoked_api_key	API key was revoked
missing_api_key	No API key provided

Permission (permission_error)

Code	Description
model_not_allowed	API key can't use this model
ip_not_allowed	Request from unauthorized IP
cost_limit_exceeded	Budget limit reached
insufficient_quota	Account quota exhausted

Rate Limit (rate_limit_error)

Code	Description
rate_limit_exceeded	Too many requests
tokens_limit_exceeded	Too many tokens per minute

Invalid Request (invalid_request_error)

Code	Description
invalid_parameter	Parameter value invalid
missing_parameter	Required parameter missing
invalid_model	Model doesn't exist
context_length_exceeded	Too many input tokens
content_policy_violation	Content blocked

Provider (provider_error)

Code	Description
provider_unavailable	Provider is down
provider_rate_limit	Provider's rate limit hit
provider_timeout	Provider didn't respond
provider_error	Provider returned error

Debugging

Request ID

Every response includes a request ID:

X-Request-Id: req_abc123xyz

Include this when contacting support.

Verbose Errors

Enable verbose errors in development:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_body={
        "gateflow": {
            "verbose_errors": True
        }
    }
)

Returns additional debugging info:

{
  "error": {
    "message": "...",
    "debug": {
      "request_id": "req_abc123",
      "timestamp": "2024-01-15T10:30:00Z",
      "provider_response": {...}
    }
  }
}