​

Troubleshooting: WhatsApp Flows API — 502 META_API_ERROR

​

Symptom map

​

Decode the META_API_ERROR variants

​

Test whether the failure is retryable

1. details.isRateLimited: true. Do not retry in a loop. Wait for Meta’s call-budget window to reset (a few minutes), then send one retry. Every extra request while throttled extends the window.
2. Code META_API_ERROR, no rate-limit tag. Retryable. Send the retry with an Idempotency-Key header so a create call cannot double-create a Flow, and add jitter (a random 0–30 seconds on top of your backoff) so a fleet of pollers does not retry in lockstep.
3. Code WHATSAPP_CONNECTION_INVALID or WHATSAPP_TOKEN_EXPIRED. Not retryable — the connection or token is deterministic-broken, so a retry returns the same thing. Reconnect from Settings → Channels → WhatsApp and retry only after the reconnect reports Connected.
4. A 4xx body-validation error on the create endpoint with none of the codes above. Not retryable until the request body is fixed — re-check the Flow JSON field-by-field before resubmitting.

​

Rate-batching guidance

• Poll the list endpoint on a schedule (minutes, not seconds) from server-side jobs, never from a re-render loop in a client.
• Page with offset instead of re-requesting the whole list — each page call also counts against the budget.
• When you are creating Flows in bulk, serialize the creates with a small delay rather than firing them concurrently.
• If a campaign the Flows tab drives needs frequent refresh, throttle the refresh on details.isRateLimited rather than on a fixed timer.

​

Escalation payload

1. The request id from the response headers of a failing call.
2. The variant branch — isRateLimited true vs absent, and the exact code and message you received.
3. Whether the same request has succeeded before — a Flows list that never succeeds is a different trace than one that broke recently.

​

What not to do

• Do not retry on a throttled WABA. details.isRateLimited: true is the signal to stop; every further request extends the window.
• Do not reconnect on a 502 META_API_ERROR. Only WHATSAPP_CONNECTION_INVALID or WHATSAPP_TOKEN_EXPIRED resolves with a reconnect; reconnecting on a plain transient blip changes nothing.
• Do not reuse an Idempotency-Key with a different body. Key reuse with a different payload is rejected; regenerate the key when the payload changes.

​

Platform-side 5xx: FLOWS_ERROR

{
  "error": {
    "code": "FLOWS_ERROR",
    "message": "Failed to list WhatsApp flows",
    "status": 500
  },
  "meta": {
    "request_id": "req_01J…",
    "timestamp": "2026-10-26T09:14:02.000Z"
  }
}

​

FLOWS_ERROR vs the Meta-side codes above

​

Responding to a FLOWS_ERROR

• Reads (list, get, funnel, submissions): retry directly. They are idempotent and change nothing on Meta.
• Create, update, publish, delete: back off, resend the same payload, then verify. Confirm against the flows list (or the flow detail page) that the operation landed before resending again. A FLOWS_ERROR means the operation did not complete, so the same payload is safe to resend; the verify step is what guarantees a retry never double-applies a create or a publish.
• Nothing is billed on a FLOWS_ERROR. The failure precedes any billable send.
• Do not reconnect the channel. As with the 502 above, the token and connection are not what failed, so reconnecting changes nothing.

​

When to escalate

​

See also

• WhatsApp channels — The Visual Flow Builder — the Flows list/create surface this page decodes, and the dashboard tab that applies the same retry gate.
• Messenger channel — MESSAGE_SEND_FAILED variants — the sibling 502 decoder this page mirrors.
• Troubleshoot a WhatsApp connection — the reconnect playbook for the WHATSAPP_CONNECTION_INVALID and WHATSAPP_TOKEN_EXPIRED branches above.
• WhatsApp Flow submissions — when the Flow loads fine but completed submissions never land in the CDP.
• WhatsApp Flow template screens — when a Flow’s screens fail to upload or render on the template side of the same surface.