Error Codes

Understand and handle ModelPilot API errors effectively.

Error Response Format

Standard Error Structure

json

{
  "error": {
    "message": "Human-readable error message",
    "type": "error_type",
    "code": "specific_error_code",
    "param": "parameter_name",  // Optional
    "retry_after": 60           // Optional, for rate limits
  }
}

HTTP Status Codes

400

Bad Request

The request was invalid or cannot be served

json

{
  "error": {
    "message": "Invalid request: missing required field 'messages'",
    "type": "validation_error",
    "code": "missing_required_field",
    "param": "messages"
  }
}

401

Unauthorized

Authentication failed or API key is missing

json

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

403

Forbidden

Valid authentication but insufficient permissions

json

{
  "error": {
    "message": "You do not have access to this router",
    "type": "authorization_error",
    "code": "router_access_denied"
  }
}

404

Not Found

The requested resource doesn't exist

json

{
  "error": {
    "message": "Router not found",
    "type": "not_found_error",
    "code": "router_not_found"
  }
}

429

Too Many Requests

Rate limit exceeded

json

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retry_after": 42
  }
}

500

Internal Server Error

Something went wrong on our end

json

{
  "error": {
    "message": "Internal server error",
    "type": "internal_error",
    "code": "internal_error"
  }
}

502

Bad Gateway

Error communicating with upstream AI provider

json

{
  "error": {
    "message": "Provider error: OpenAI API unavailable",
    "type": "provider_error",
    "code": "provider_error"
  }
}

503

Service Unavailable

Service temporarily unavailable

json

{
  "error": {
    "message": "Service temporarily unavailable",
    "type": "service_unavailable_error",
    "code": "service_unavailable"
  }
}

Common Error Types

Authentication Errors

invalid_api_key - API key is invalid or expired
missing_api_key - No API key provided
revoked_api_key - API key has been revoked

Router Errors

router_not_found - Router ID doesn't exist
router_inactive - Router is disabled
router_access_denied - No permission to use this router

Billing Errors

insufficient_credits - Not enough credits for request
payment_required - Payment method required
subscription_expired - Subscription has expired

Model Errors

model_not_available - Requested model unavailable
context_length_exceeded - Input too long for model
invalid_model - Model not supported

Handling Errors

Try-Catch Pattern

javascript

import ModelPilot from 'modelpilot';

const client = new ModelPilot({
  apiKey: process.env.MODELPILOT_API_KEY,
  routerId: process.env.MODELPILOT_ROUTER_ID,
});

try {
  const completion = await client.chat.completions.create({
    messages: [{ role: 'user', content: 'Hello!' }],
  });
  console.log(completion.choices[0].message.content);
} catch (error) {
  // Handle specific error types
  if (error.status === 401) {
    console.error('Authentication failed:', error.message);
    // Refresh API key
  } else if (error.status === 429) {
    console.error('Rate limit exceeded');
    // Wait and retry
    const retryAfter = error.retry_after || 60;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (error.status === 402) {
    console.error('Insufficient credits');
    // Redirect to billing page
  } else {
    console.error('API error:', error.message);
  }
}

Error Type Checking

javascript

try {
  const completion = await client.chat.completions.create({
    messages: [{ role: 'user', content: 'Hello!' }],
  });
} catch (error) {
  switch (error.type) {
    case 'authentication_error':
      // Handle authentication issues
      break;
    case 'rate_limit_error':
      // Handle rate limiting
      break;
    case 'insufficient_credits':
      // Handle billing issues
      break;
    case 'provider_error':
      // Upstream provider issue
      break;
    default:
      // Generic error handling
      console.error('Unexpected error:', error);
  }
}

Best Practices

Always handle errors gracefully
Never expose raw error messages to end users
Implement retry logic
Use exponential backoff for transient errors
Log errors for debugging
Include request IDs and context
Monitor error rates
Set up alerts for unusual error patterns

Next Steps

Rate Limits

Understanding rate limiting

API Reference

Complete API documentation