When a request fails, the API answers with an HTTP status and a body of type application/problem+json (RFC 9457). Branch on code, not on detail: codes are stable, while the human-readable text may change.
{"field":"to[1]","message":"must be a valid E.164 phone number"},
{"field":"metadata","message":"must be at most 4096 bytes of JSON"}
],
"requestId":"req_u7x0a3d6g9j2m5p8s1v4y7b0"
}
Field
Meaning
type
A URI that names the problem.
title
The HTTP status text.
status
The HTTP status, repeated.
detail
What went wrong, for a person. May change wording.
code
Stable machine code. Listed below.
errors
Present on validation errors: one entry per invalid field. Nested fields use dots (quietHours.start), array items use brackets (to[1]).
params
Present on plan refusals: the values behind detail (the plan, the limit, what was limited, when it resets), so you can word the error yourself. See Plan errors.
requestId
Quote it when you contact support.
Unknown fields in a request body are rejected too (validation_failed, with a message such as property foo should not exist), so a typo in a field name never fails silently.
No. The plan’s daily or monthly allowance is used up; sending works again at params.resetsAt.
503 maintenance
Yes, after Retry-After seconds.
500, 503, network errors and timeouts
Yes, with exponential backoff and the same Idempotency-Key (see Idempotency).
The Node SDK does this for you: it retries network errors, 429, 5xx and 409 idempotency_in_progress twice by default, honouring Retry-After. Other 409 codes are thrown at once, and the error’s retryAfter holds the wait in seconds. It never retries 429 quota_exceeded.
Your plan sets how many phones, seats, API keys and webhook endpoints you can have, how many messages you can send per day and per month, and which features you can use (Plans). A refused request changes nothing and sends nothing.
Status
code
Meaning
What to do
403
plan_limit_reached
The plan has no room for another phone, seat, API key or webhook endpoint, or a send has more recipients than the plan allows per request.
Remove one you no longer use, split the send, or ask for a plan change.
403
feature_not_in_plan
The plan does not include the feature: pools, scheduled sends or CSV export.
Ask for a plan that includes it.
429
quota_exceeded
The daily or monthly message allowance is used up.
Don’t retry in a loop. Sending works again at params.resetsAt; GET /v1/org/plan shows dayResetsAt and monthResetsAt.
These errors carry params beside the English detail:
code
params
plan_limit_reached
{ plan, resource, limit }. resource is phones, seats, apiKeys, webhooks or recipients.
feature_not_in_plan
{ plan, feature }. feature is pools, scheduled_sends or csv_export.
quota_exceeded
{ plan, period, limit, resetsAt }. period is day or month; resetsAt is an ISO 8601 time in UTC.
plan is the plan’s display name. plan_limit_reached and quota_exceeded also carry limit at the top level.