Errors

Every response carries a meaningful HTTP status code. A 2xx means the request was accepted; anything else signals a problem your code should handle explicitly. Error bodies, when present, are JSON with a message field describing the failure.

Status codes

400 Bad Request

The request body is malformed or has the wrong shape. Not retryable — fix the payload first.

HTTP/1.1 400 Bad Request

{ "message": "Problems parsing JSON" }

{ "message": "Body should be a JSON object" }

401 Unauthorized

The token is missing, revoked or malformed. Not retryable with the same token — check the Authentication guide.

HTTP/1.1 401 Unauthorized

402 Payment Required

The account has run out of balance. Not retryable until funds are topped up in the dashboard.

HTTP/1.1 402 Payment Required

404 Not Found

The resource (message id, token id, project) does not exist or is not visible to the current token.

HTTP/1.1 404 Not Found

413 Request Too Large

The request body exceeds the maximum accepted size. Not retryable — trim the payload.

HTTP/1.1 413 Request Too Large

429 Too Many Requests

You hit the per-endpoint rate limit. Retry after X-RateLimit-Reset. See Rate limits.

HTTP/1.1 429 Too Many Requests

500 Internal Server Error

Something broke on our side. Retry with exponential backoff; if the failure persists, contact support with the request id.

HTTP/1.1 500 Internal Server Error

Retry policy

What's next

• Receiving DLRs — delivery reporting for messages that did leave the API successfully.
• API Reference — per-endpoint responses.