Using the API well

Errors

Every error has the same shape, a stable code you can branch on, and a docUrl that links to its entry on this page.

The error object

error response

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "SERVICE_WINDOW_CLOSED",
    "type": "policy_error",
    "message": "Free-form messages require an open 24-hour service window.",
    "retryable": false,
    "retryAfterSeconds": null,
    "docUrl": "https://toutye.com/docs/errors#SERVICE_WINDOW_CLOSED",
    "requestId": "req_FjLKGlzDxsiDKsIz",
    "providerCode": 131047,
    "details": [{ "path": "type", "issue": "…" }]
  }
}

retryable is the only thing that says whether retrying can help. When it is true, wait retryAfterSeconds (or the Retry-After header) and retry with the same Idempotency-Key.
providerCode is WhatsApp’s own error code, when the refusal came from WhatsApp.
details lists each invalid field for validation errors.
Quote requestId when you contact support; it also finds the call in your request log.

The same list is available as JSON at GET /v1/errors (no key needed). Failed messages carry the same codes in data.error on message.failed.

Error codes

API error messages below are shown exactly as returned by the API. The explanations are translated.

Code	Message and what to do
`SIGNING_UNAVAILABLE`	503RetryableRequest signing verification is temporarily unavailable.Authentication Signature checking is briefly unavailable. Retry after a short wait; nothing was processed.
`PROVIDER_TEMPORARY_ERROR`	502RetryableThe provider returned a temporary error.WhatsApp (provider) WhatsApp had a temporary failure. Retrying is safe; queued messages are retried automatically.
`PROVIDER_PERMANENT_ERROR`	502Not retryableThe provider returned a permanent error.WhatsApp (provider) WhatsApp refused the request for good. `providerCode` has Meta's reason; change the request before trying again.
`PROVIDER_RESULT_UNKNOWN`	502Not retryableThe provider result is unknown.WhatsApp (provider) WhatsApp did not say whether it accepted the message. Toutye does not resend it blindly; the final status arrives as an event, or the message is reported as unknown.
`PROVIDER_TOKEN_INVALID`	502Not retryableThe provider credential is invalid.WhatsApp (provider) The WhatsApp connection's credential is no longer valid. Reconnect the WhatsApp Business Account.
`WABA_RESTRICTED`	502Not retryableThe WABA is restricted by the provider.WhatsApp (provider) WhatsApp has restricted the business account. The console shows the reason and any appeal path.
`PAYMENT_REQUIRED`	502Not retryableThe provider requires a payment method on the WABA.WhatsApp (provider) WhatsApp needs a payment method on the WhatsApp Business Account before it will send.
`REGISTRATION_ERROR`	502Not retryableSender registration failed at the provider.WhatsApp (provider) WhatsApp refused to register the phone number. Check the number and its verification code.
`MEDIA_PROVIDER_ERROR`	502Not retryableThe provider could not process the media.WhatsApp (provider) WhatsApp could not process the media file. Try another format or a smaller file.
`FLOW_ERROR`	502Not retryableThe Flow is blocked or throttled.WhatsApp (provider) WhatsApp blocked or throttled the Flow.
`MARKETING_MESSAGES_ERROR`	502Not retryableMarketing Messages API error.WhatsApp (provider) The Marketing Messages API refused the message; `providerCode` has the reason.
`RECIPIENT_UNREACHABLE`	502Not retryableThe recipient cannot receive WhatsApp messages.WhatsApp (provider) The number does not have WhatsApp or cannot receive messages. Do not retry.
`RECIPIENT_IN_EXPERIMENT`	502Not retryableThe recipient is in a provider experiment group.WhatsApp (provider) WhatsApp is holding back marketing messages to this person as part of its own experiment. Nothing to fix.
`TEMPLATE_PROVIDER_ERROR`	502Not retryableThe provider rejected the template message.WhatsApp (provider) WhatsApp rejected the template message, usually for wrong or missing parameters. Compare the parameters with the template.
`DISPLAY_NAME_NOT_APPROVED`	502Not retryableThe sender display name is not approved.WhatsApp (provider) The sender's display name is not approved by WhatsApp yet, so it cannot send.
`INTERNAL_TEMPORARY_ERROR`	500RetryableA temporary internal error occurred.Toutye internal A temporary failure inside Toutye, including load shedding under heavy demand (HTTP 503 with a `Retry-After` header and `retryAfterSeconds`; nothing was saved and no RateLimit headers are sent). Wait, then retry with the same Idempotency-Key.
`REGION_DIRECTORY_UNAVAILABLE`	503RetryableRegional account routing is temporarily unavailable.Toutye internal Regional discovery is temporarily unavailable. Wait before retrying, or use your account's known regional API address. Keep the same Idempotency-Key when retrying a mutation.
`REGIONAL_API_UNAVAILABLE`	502RetryableThe account's regional API is temporarily unavailable.Toutye internal Your account's regional API could not be reached. A mutation may already have been accepted: check its status and reuse the same Idempotency-Key when retrying. Do not send it to a different region.
`INTERNAL_PERMANENT_ERROR`	500Not retryableAn internal error occurred.Toutye internal An unexpected failure inside Toutye. Contact support with the `requestId`.
`MESSAGE_BUILD_FAILED`	500Not retryableThe message could not be prepared for sending; nothing was sent to the provider.Toutye internal Toutye could not assemble the message (for example a template variable could not be filled). Nothing was sent.
`WEBHOOK_DELIVERY_ERROR`	500Not retryableWebhook delivery failed.Toutye internal Delivering an event to your endpoint failed. It is retried with backoff; see the webhook's delivery log.