Error Handling

Understanding API error codes and troubleshooting

HTTP Status Codes

Our API uses standard HTTP status codes to indicate the success or failure of requests. Here are the most common error codes you may encounter:

400

Bad Request

Invalid request parameters or format

Example Response:

JSON

{
  "code": "INVALID_PHONE_NUMBER",
  "error": "Invalid phone number format"
}

401

Unauthorized

Missing or invalid API key

Example Response:

JSON

{
  "code": "INVALID_API_KEY",
  "error": "Invalid API key"
}

429

Too Many Requests

Rate limit exceeded

Example Response:

JSON

{
  "code": "RATE_LIMIT_EXCEEDED",
  "error": "Rate limit exceeded",
  "retry_after": 3600
}

Error Handling Best Practices

🔍 Always Check Status Codes

Before processing response data, always check the HTTP status code to ensure the request was successful.

🔄 Implement Retry Logic

For 5xx errors and rate limits (429), implement exponential backoff retry logic with appropriate delays.

📝 Log Error Details

Log both the error code and message for debugging. Include request details for better troubleshooting.

🛡️ Handle Gracefully

Provide meaningful error messages to users and implement fallback mechanisms where possible.

Common Error Scenarios

Invalid Phone Number Format

Ensure phone numbers are in E.164 format (e.g., +15551234567) or 10-digit US format.

JSON

{
  "error": "Invalid phone number format",
  "code": "INVALID_PHONE_NUMBER",
  "details": "Phone number must be in E.164 format"
}

API Key Issues

# Around line 117

Make sure your API key is included in the Authorization: Bearer header and is valid.

# Around line 159

Ensure Authorization header with Bearer token is included

JSON

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": "Please check your API key and try again"
}

Rate Limiting

When you exceed rate limits, wait for the specified retry_after period before making new requests.

JSON

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 3600,
  "details": "Please wait 1 hour before making new requests"
}

Troubleshooting Guide

Step 1: Verify Request Format

Check that Content-Type is set to application/json
Ensure X-API-Key header is included
Validate JSON syntax in request body

Step 2: Check API Key

Verify API key is active in your dashboard
Ensure no extra spaces or characters
Check if key has necessary permissions

Step 3: Review Rate Limits

Check current usage in your dashboard
Implement proper rate limiting in your code
Consider upgrading your plan if needed

💡 Need Help?

If you're still experiencing issues after following this guide, please contact our support team at support@verirouteintel.io with your error details and request information.