API Error Codes & Handling

Error Response Format

All error responses include a JSON body with an error field describing the issue.

HTTP Status Codes

• 400 Bad Request — Missing required fields or invalid data types. Check your request body.
• 401 Unauthorized — Invalid or missing API key. Verify your Authorization header.
• 402 Insufficient Credits — Your balance cannot cover this send. Top up your credits.
• 403 Forbidden — Account not approved or sender ID not verified. Complete KYC.
• 404 Not Found — The requested resource doesn't exist.
• 429 Rate Limited — Too many requests. Slow down and implement backoff.
• 500 Server Error — Internal error. Retry after a few seconds. If persistent, contact support.

Graceful Error Handling

• Always check the HTTP status code before parsing the response body
• Log error responses for debugging
• Implement retry logic for 429 and 500 errors only
• Do not retry 400, 401, 402, or 403 errors — fix the underlying issue first
• Show user-friendly messages to your end users