> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting: WhatsApp Flows API — 502 META_API_ERROR > Decode the 502 META_API_ERROR envelope returned by the WhatsApp Flows list/create endpoints, decide whether to retry with an Idempotency-Key or fix the connection, and batch Flows API calls so you stay under Meta's per-WABA call budget. # Troubleshooting: WhatsApp Flows API — 502 META\_API\_ERROR The Flows list (`GET /api/v1/whatsapp/flows`) and Flows create endpoints proxy Meta's Graph API. When Meta's side of the call fails, Orbit returns a deliberately mapped error rather than passing Meta's raw body through — so a 502 on these endpoints is not a raw upstream crash, it is a classified envelope you can decode. This page covers that envelope. If the problem is a Flow's runtime (screen render, encrypted exchange) work [Flow execution failures](/troubleshooting/flow-executions-failed) instead; if the WABA itself is disconnected, work [Troubleshoot a WhatsApp connection](/troubleshooting/whatsapp-connection). The reconnect, publish-state, and token-recovery levers this page points at are all tenant-owned — Orbit's role is to classify the upstream response so you know which lever to pull. ## Symptom map Work the table top-down — it covers the failure modes that account for nearly every 502 on the Flows endpoints. | Symptom | Most likely cause | What to do | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **502 `META_API_ERROR` on the Flows list** | Meta returned a 5xx / 429 / 408, or the WABA hit its Meta call budget | Decode the variant below — transient blips are retryable; a throttled WABA needs a wait, not a reconnect | | **502 `META_API_ERROR` right after a burst of Flows-tab or API polls** | The WABA burned its Meta call budget on repeated list calls | Stop auto-retrying; see the rate-batching section. The response carries `details.isRateLimited: true` | | **`WHATSAPP_CONNECTION_INVALID` on the Flows list** | The WABA is missing the `whatsapp_business_management` permission, or the saved `waba_id` is wrong | Reconnect the channel from **Settings → Channels → WhatsApp** | | **`WHATSAPP_TOKEN_EXPIRED` on the Flows list** | Meta rejected the saved access token (it expired or was revoked) | Reconnect the integration from **Settings → WhatsApp** — the token is replaced on reconnect | ## Decode the META\_API\_ERROR variants A 502 with `code: "META_API_ERROR"` bundles different upstream failures behind one code. The Messenger channel page uses the same pattern for its `MESSAGE_SEND_FAILED` 502 — read `details.provider_message` first, then pick the fix. Here the discriminator is `details.isRateLimited`: | Signal | Variant | Fix | | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `details.isRateLimited: true` | Meta is throttling the WABA's call budget — typically surfaced as Meta's `(#80008) too many calls` family, which arrives on a plain HTTP 4xx rather than a 429 | Stop auto-retrying; wait for Meta's window to reset, then retry once. Batch Flows calls as below | | `details.isRateLimited` absent, message matches "temporarily unavailable" | Transient Meta outage or a 429/408 gateway condition | Retry with an `Idempotency-Key` and jitter — see the retry test | The dashboard Flows tab already stops auto-retrying when `details.isRateLimited: true` — if you built your own poller against the list endpoint, apply the same gate or you will burn the WABA's call budget. ## Test whether the failure is retryable Run this decision in order — the first branch that matches is the answer: 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 The throttled-WABA variant is nearly always self-inflicted — the Flows list endpoint is cheap to call in a loop, and Meta counts that loop against the WABA's call budget. Keep the budget intact: * 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 If you have worked the page and the same 502 persists across a WABA that is not throttled, email [whatsapp-support@devotel.io](mailto:whatsapp-support@devotel.io) with these three items so we can trace the upstream call without a back-and-forth: 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. ## See also * [WhatsApp channels — The Visual Flow Builder](/channels/whatsapp#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](/channels/messenger#common-errors) — the sibling 502 decoder this page mirrors. * [Troubleshoot a WhatsApp connection](/troubleshooting/whatsapp-connection) — the reconnect playbook for the `WHATSAPP_CONNECTION_INVALID` and `WHATSAPP_TOKEN_EXPIRED` branches above. * [WhatsApp Flow submissions](/troubleshooting/whatsapp-flow-submissions) — when the Flow loads fine but completed submissions never land in the CDP.