Guides

Errors

Errors use standard HTTP status codes and one JSON envelope, so you can handle them in one place.

Error envelope

error.code is stable and safe to branch on; error.message is for people. Include requestId when you contact support — it lets us find the exact request.

Error response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "body/phone must match format",
    "details": {}
  },
  "requestId": "a1f4c2e0-9b6d-4a1e-8c3f-2d7e5b9a0c11",
  "timestamp": "2026-07-12T09:30:00.000Z",
  "path": "/api/public/v1/messages",
  "method": "POST"
}

Status codes

400Bad Request

Why: The request was malformed or the tenant context headers are missing.

Fix: Send a valid x-tenant-id header and a well-formed request body.

Example code ACCOUNT_CONFIGURATION_ERROR

401Unauthorized

Why: The API key or OAuth access token is missing, malformed, or invalid.

Fix: Send a valid API key via x-api-key (or Authorization: Bearer), or a valid OAuth access token.

Example code API_KEY_INVALID

403Forbidden

Why: The developer platform is disabled, the credential lacks the required scope, or the tenant does not match.

Fix: Enable the developer platform, request the required OAuth scope, or verify the tenant/product context.

Example code OAUTH_INSUFFICIENT_SCOPE

404Not Found

Why: The requested resource does not exist (or is not visible to this tenant).

Fix: Verify the resource id and that it belongs to the authenticated tenant.

Example code CONTACT_NOT_FOUND

409Conflict

Why: The request conflicts with the current state, e.g. a duplicate unique value.

Fix: Fetch the existing resource or use a different unique value.

Example code DUPLICATE_PHONE

422Unprocessable Entity

Why: Validation failed for one or more fields.

Fix: Inspect error.details.issues and correct the offending fields.

Example code VALIDATION_ERROR

429Too Many Requests

Why: The rate limit for this API key (or IP) was exceeded.

Fix: Back off and retry after the window resets. Inspect error.details for the limit and remaining time.

Example code RATE_LIMIT_EXCEEDED

500Internal Server Error

Why: An unexpected error occurred on the server.

Fix: Retry after a short delay. If it persists, contact support with the requestId.

Example code INTERNAL_SERVER_ERROR

What to retry

Retry 429 (after the reset time) and 5xx with exponential backoff.
Don't retry other 4xx errors — fix the request first.
Sending is asynchronous: a 202 means queued, not delivered. Watch webhooks for message.failed.

PreviousOAuth 2.0 NextRate limits