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": "Too many requests. Please retry after 12 seconds.",
    "code": 4029,
    "request_id": "req_01H9...XQ"
  }
}

---

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
4020	quota_exceeded	Monthly plan quota reached	Upgrade your plan
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 retry_after seconds

Validation Errors (400, 422)

Code	Type	Description	Fix
4000	invalid_request	Generic validation failure	Check the details field for field-level errors
4001	invalid_phone	Phone number is not valid E.164	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
4004	recipient_suppressed	Address is on your suppression list	Remove from suppression list in dashboard if unintended
4005	invalid_template	Template ID not found or template is not approved	Verify the template exists and is approved by Meta

OTP / Verify Errors

Code	Type	Description	Fix
4040	verification_not_found	id does not match any verification	Ensure you're passing the ID from /verify/send
4041	verification_expired	OTP TTL has passed	Ask the user to request a new OTP
4042	max_attempts_exceeded	5 wrong attempts — locked	Start a new verification session
4043	otp_rate_limit	Too many OTPs sent to this number	Wait before sending another OTP

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