Skip to main content
Start with the HTTP status and the code in the error body. Every error includes a trace_id, which lets Ringg find the request in seconds. Keep it in your logs.

​
Rejected requests

​
401 missing_api_key or invalid_api_key

The X-API-Key header is missing, or the key isn’t a current key for your workspace.
  • Check you are using the key for the right environment: staging and production keys differ.
  • If the key was regenerated in the dashboard, update your service.

​
403 invalid_signature

The signature didn’t match, or the timestamp was out of range. In order of how often we see them: When Ringg rotates a secret, the old one keeps working until it is retired, so a rotation alone doesn’t cause this error.

​
403 workspace_mismatch

The API key works, but its workspace doesn’t own the phone_number_id in the body. Use the key of the workspace the number is registered to.

​
404 unknown_phone_number_id

The number isn’t registered for relay in this environment. Check the phone_number_id is Meta’s numeric id for the number, not the display number, and that you are calling the environment it was registered in.

​
422 invalid_body

The body doesn’t match the endpoint’s shape. The message names the field. Common causes:
  • Extra top-level fields. Every relay body accepts only its documented fields. On /status, send { "phone_number_id": "…", "statuses": [ … ] } only, not Meta’s whole entry or value wrapper.
  • prior_messages too long, or a message with empty text. Up to 200 messages, each 1 to 4,096 characters.
  • role not customer or agent.
  • A wrong type, such as chat_id not being a UUID on /ack or /close.

​
422 missing_message_id

value.messages[0].id is empty. Forward Meta’s original message id: it is how Ringg avoids answering the same message twice.

​
503 errors

unable_to_accept, auth_unavailable, config_unavailable and relay_unavailable are temporary. Retry with backoff. Retrying /inbound with the same message id is always safe.

​
No reply for a message

/inbound answers 202 as soon as the message is stored. If no message.outbound follows, check these in order: If none of these explain it, send Ringg the phone_number_id, the customer message id and the time.

​
Replies arrive out of order

Ringg delivers one reply per chat at a time, in sequence order. Out-of-order messages on WhatsApp usually mean your service sends to Meta in parallel. Send each chat’s replies one at a time, in sequence order.

​
Acks

Ack every message.outbound, even when the send failed. A failed or skipped ack keeps the AI agent from referring to a message the customer never saw.

​
Handover history looks wrong

​
A chat closed unexpectedly

A chat closes when:
  • the AI agent ends it (conversation.closed, reason: "completed");
  • you call /close;
  • you ack a reply as failed with Meta error 131047 (24-hour window closed), 131026 (undeliverable) or 131051 (unsupported type);
  • it reaches the agent’s idle or maximum-length timeout.
The customer’s next message starts a new chat.

​
What to send Ringg support

  • The trace_id from any error response
  • The phone_number_id, chat_id and event_id involved
  • The customer message id (wamid…), if a reply is missing
  • The time, with time zone
  • Environment: staging or production