Errors, rate limits and API compatibility
Handle HTTP failures, product limits and uncertain write outcomes without duplicating a payment or message.
Reviewed against the implementation · 2026-10-30
Read the HTTP status and endpoint error
Error bodies differ by endpoint. Many return an error string; some include message, details, field errors or a statusCode. Do not require those optional fields in a universal parser. Read the HTTP response status even if the body cannot be parsed as JSON. Show a useful fallback and retain the request identifier when supplied.
Authentication and permissions
A 401 generally requires a valid credential or fresh session. A 403 indicates an authorization, scope or policy failure; repeating the request will not grant access. A 404 may mean a resource is absent or not visible to the caller. Check workspace, agent permissions and product access rather than assuming an ID is global.
Validation, credits and conflicts
Use the endpoint-specific 400 or 422 error to correct the request. Payment, credit and plan gates can return 402. A 409 can represent a stale version, assignment conflict or operation already in progress. Reload the current resource and resolve the conflict before retrying. An unavailable Verify channel returns channel_not_available; a new credential does not make that channel available.
Rate limits
The general request limiter allows 600 requests per minute per verified agent, with an IP-based fallback for unauthenticated traffic. Routes can impose different limits, and products also enforce credit, destination, daily-volume and anti-abuse limits. Do not assume the general rate is a safe send rate for SMS, iMessage or calls.
Backoff and uncertain writes
For 429, respect Retry-After when present and the endpoint-specific retry information. Use bounded exponential backoff with jitter when no valid delay is provided. Read-only operations may be retried after a transient failure. Before repeating a write after a timeout or 5xx, query its status or use the documented idempotency mechanism. Do not automatically repeat purchases, number registrations or sends.
Versioning and forward compatibility
The published REST paths use /api/v1. There is no implemented Message-Version date-pin header: sending one does not freeze behavior to that date. Clients should tolerate additional response fields and unknown enum values. Consult the specific endpoint reference and test an integration against the current contract; do not rely on an unpublished twelve-month deprecation guarantee.
Report a failure safely
Provide the route, method, time, status and redacted error to support. Never include API keys, session cookies, OTP codes or unneeded customer information. Keep the user informed when the result is uncertain rather than reporting success or charging again.