Common API Errors and What They Mean

API Errors, Translated

If your integration is throwing errors, the status code tells you what to fix.

401 Unauthorized

Your API key is missing, wrong, or revoked. Check the Authorization header and confirm the key under Portal > Developer. Regenerate it if you're unsure — old keys stop working immediately when you do.

402 / Insufficient Credits

Your balance can't cover the send. Top up at Portal > Billing. Tip: set a low-balance alert so this never interrupts production traffic.

422 Unprocessable

The request reached us but a field is invalid. Usual culprits: a phone number not in 2557XXXXXXXX format, an empty message body, or a Sender ID that isn't approved on your account.

429 Too Many Requests

You're sending faster than your rate limit. Batch recipients into a single bulk call instead of many single calls, and add a small backoff on retry.

5xx Server errors

Rare, and on us — retry with exponential backoff. If it persists, send us the request ID from the response and we'll investigate immediately.

Good habits

• Always send an idempotency key so retries don't double-send.
• Log the full response body — our errors include a human-readable reason.
• Use webhooks for delivery status instead of polling.