Errors

The error response shape, HTTP status codes, and common validation failures.

Last updated 05 Aug 2026

Every Riffre API error uses the same JSON shape, regardless of endpoint:

{
  "error": "recipient_must_use_international_format",
  "message": "Recipient must use international format."
}

error is a stable, machine-readable snake_case slug you can match on in code.
message is a human-readable description safe to log or show to a developer (not intended for end users).

HTTP status codes

Status	Meaning	Typical cause
202	Accepted	The message was validated and queued for delivery.
201	Created	A media file was uploaded successfully.
401	Unauthorized	Missing, malformed, invalid, disabled or expired API key.
405	Method Not Allowed	Any method other than `POST` was used.
422	Unprocessable Entity	The request body was invalid JSON, or failed validation (bad `to`, bad `type`, a field outside its allowed length, an unsupported media MIME type, and so on).
429	Too Many Requests	The account's rate limit was exceeded. See Rate Limits.
402	Payment Required	The account's wallet balance is too low, or the account maintenance fee for this WhatsApp number has not been paid.
500	Internal Server Error	An unexpected failure occurred while queueing the message.

The message field of a 422 response describes exactly which field failed and why, for example:

{"error": "text_body_must_contain_between_1_and_4096_characters", "message": "Text body must contain between 1 and 4096 characters."}

{"error": "image_must_contain_exactly_one_of_id_or_link", "message": "Image must contain exactly one of id or link."}

Validation is designed to fail fast and specifically, so you rarely need to guess which field was wrong.

401 and 422 errors will not succeed on retry without changing the request - fix the underlying issue first.
429 errors should be retried after the duration in the Retry-After header.
402 errors mean your wallet balance is too low, or the account maintenance fee for this WhatsApp number is unpaid - add funds from the dashboard Usage & Billing page, then retry.
500 errors may be transient and can usually be retried as-is.