API Errors & Responses

Complete reference for error codes, messages, and handling best practices for VeriRoute Intel APIs.

Response Formats

VeriRoute Intel APIs use two response formats depending on the endpoint. Always check for both patterns when handling errors.

Format A: Data/Errors Envelope

Used by Trust, Spam, and some legacy endpoints

{
  "data": { ... },
  "errors": ["Error message here"]
}

Format B: Standard Error

Used by CNAM, LRN, Messaging, and newer endpoints

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": { ... }
}

Error Code Glossary

Complete reference of all error codes with descriptions and suggested resolutions.

Code	HTTP	Description	Resolution
`INVALID_API_KEY`	401	API key not found or invalid	Verify key in dashboard, check for typos
`MISSING_API_KEY`	401	No API key provided in request	Add `Authorization: Bearer YOUR_KEY` header
`INSUFFICIENT_BALANCE`	402	Account balance too low	Add funds via billing page
`INVALID_PHONE_NUMBER`	400	Phone number format not recognized	Use E.164 format or 10-digit US number
`INTERNATIONAL_NOT_SUPPORTED`	400	Non-NANP number provided	Only US/CA numbers supported
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Wait for `retry_after` seconds, implement backoff
`DUPLICATE_REPORT`	429	Already reported this number recently	Wait 24 hours before re-reporting same number
`INVALID_REPORT_TYPE`	400	Unknown spam report type	Use: spam, robocall, scam, telemarketing, fraud, phishing
`BATCH_SIZE_EXCEEDED`	400	Too many numbers in batch	Max 1000 for bulk, 100 for batch spam
`PROVIDER_ERROR`	503	Upstream provider unavailable	Retry after a few seconds
`INTERNAL_ERROR`	500	Server-side error	Retry; contact support if persistent

HTTP Status Codes

Our API uses standard HTTP status codes to indicate the success or failure of requests.

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
}

Troubleshooting

🔍 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 Issues

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.com with your error details and request information.