Error Codes

Relai uses standard HTTP status codes and returns detailed error information in the response body.

Error Response Format

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "specific_error_code",
    "param": "field_name"
  }
}

HTTP Status Codes

Common Error Types

Authentication Errors (401)

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

Solutions:

• Check your API key starts with relai_sk_eu_live_, relai_sk_us_live_, relai_sk_gbl_eu_live_ or relai_sk_gbl_us_live_
• Verify the key hasn't been revoked
• Ensure the Authorization header format is Bearer YOUR_KEY

Rate Limit Errors (429)

{
  "error": {
    "message": "Rate limit exceeded: 60 requests per minute",
    "type": "rate_limit_exceeded",
    "retry_after": 12
  }
}

Solutions:

• Wait for the retry_after seconds
• Implement exponential backoff
• Increase your key's RPM limit in the dashboard

End User Quota Exceeded (429)

{
  "error": {
    "code": "end_user_quota_exceeded",
    "message": "End user monthly quota exceeded",
    "type": "api_error"
  }
}

Solutions:

• Increase the user's quota via PATCH /v1/users/{external_id}
• Wait for the quota period to reset (monthly: 1st of month, daily: midnight UTC)
• Omit the user field to use organization balance instead
• Check current spend with GET /v1/users/{external_id}

Insufficient Balance (402)

{
  "error": {
    "message": "Insufficient credit balance",
    "type": "insufficient_balance",
    "balance_micro": 0,
    "required_micro": 150000
  }
}

Solutions:

• Add credits in the dashboard billing page
• Enable auto-recharge to prevent interruptions

Region Mismatch (403)

{
  "error": {
    "message": "API key is for region EU, but request was made to US",
    "type": "region_mismatch"
  }
}

Solutions:

• Use api.eu.llmrelai.com with relai_sk_eu_live_… keys
• Use api.us.llmrelai.com with relai_sk_us_live_… keys
• Or create a global key (relai_sk_gbl_eu_live_…) which can be used on any region — see Regions & Key Scopes.

Home Region Unreachable (503)

{
  "error": {
    "code": "home_region_unreachable",
    "message": "Home region unreachable for global key",
    "type": "api_error"
  }
}

Returned when a global key is used on a peer region but the home region's gateway cannot be reached for authentication. This is almost always transient.

Solutions:

• Retry the request (use exponential backoff).
• Check Relai status. If you specifically need EU processing for an EU customer, you can also retry against api.eu.llmrelai.comdirectly (the key's home region), which avoids the cross-region hop.

Retry Strategy

For transient errors (429, 502, 503), implement exponential backoff:

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      const status = error.status;
      if (![429, 502, 503].includes(status)) throw error;
      
      const delay = Math.min(1000 * Math.pow(2, i), 30000);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Getting Help

If you encounter persistent errors:

1. Check our status page
2. Contact support at support@llmrelai.com
3. Include the X-Request-Id header from the response