Error Codes Reference

Complete list of all SendAPI error codes, their causes, and recommended remediation steps.

HTTP Status Codes

HTTP Code	Meaning
200 OK	Request succeeded
201 Created	Resource created
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Valid key but insufficient permissions
404 Not Found	Resource not found
409 Conflict	Conflict with existing resource
410 Gone	Resource expired (e.g., OTP)
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
402 Payment Required	Quota exceeded, plan upgrade needed
500 Internal Server Error	Unexpected server error

---

Error Response Format

All errors return a consistent JSON structure:

{
  "success": false,
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "code": 4029
  },
  "meta": {
    "request_id": "req_01H9...XQ",
    "timestamp": "2026-03-09T14:30:00.000000Z"
  }
}

---

Authentication Errors (401, 403)

Code	Type	Description	Fix
4010	missing_api_key	No Authorization header provided	Add Authorization: Bearer sk_live_... header
4011	invalid_api_key	API key is malformed or not recognized	Check the key value — it should start with sk_live_
4012	revoked_api_key	The API key has been revoked	Create a new key in the dashboard
4013	expired_api_key	The key's expiry date has passed	Create a new key in the dashboard
4030	insufficient_scope	Key lacks permission for this endpoint	Issue a key with the required scope

Quota and Billing Errors (402, 429)

Code	Type	Description	Fix
402	email_quota_exceeded	Monthly email quota reached	Upgrade your plan
402	subscription_required	No active subscription	Subscribe to a plan
402	subscription_expired	Trial expired or subscription cancelled	Renew or upgrade
4021	sms_balance_low	Insufficient SMS credit balance	Top up credits in billing dashboard
4029	rate_limit_exceeded	Too many requests per minute	Back off and retry after the Retry-After header

Validation Errors (400, 422)

Code	Type	Description	Fix
422	validation_error	Generic validation failure	Check the errors field for field-level details
4001	invalid_phone	Phone number is not valid	Use the Phone Validation endpoint to normalize
4002	invalid_session	session_id does not exist or is not yours	List sessions to find the correct ID
4003	session_not_connected	Session exists but is not connected	Check session status; re-pair if disconnected
422	invalid_from	The from value is not a valid RFC 5322 email	Use email@domain or "Name <email@domain>"
422	invalid_from_domain	Domain in from is not verified on your account	Verify the domain in Email Domains or omit from

OTP / Verify Errors

Code	Type	Description	Fix
404	not_found	No pending OTP exists for the recipient	Send a new OTP first
4291	rate_limit_exceeded	More than 5 OTPs sent to this phone in the last hour	Wait up to an hour before resending
4292	daily_limit_exceeded	More than 20 OTPs sent to this phone today	Wait until 24h after the first send

Authentication / Verification Gate Errors (403)

Code	Type	Description	Fix
403	email_not_verified	Account email is not verified	Click the verification link sent at signup
403	admin_required	Admin-only endpoint	This endpoint is internal — not for end-user keys

Server Errors (500)

Code	Type	Description	Fix
5000	internal_error	Unexpected server error	Retry with exponential backoff; contact support if persistent
5001	provider_error	Downstream SMS/WhatsApp provider error	Retry; check the dashboard for system status