Errors & rate limits
The error shape, every stable error code and the request rate limit.
Errors
Errors are {"error":{"message":"…","code":"…"}}; code is present when there is a stable one.
| Status | Code | Meaning |
|---|---|---|
| 400 | — | Invalid input (message explains which field) |
| 401 | — | Missing, unknown or revoked API key |
| 403 | approval_required | Approval applies to the key, organization or account: ads writes are refused. Other agent actions are not refused: they answer 202 pending_approval (see Approval) |
| 403 | missing_permission | The account did not grant the permission; add it to the Meta app, then reconnect the account |
| 404 | — | Unknown id, or it belongs to another organization |
| 409 | reconnect_required | The token is no longer valid; the account is needs_reconnect |
| 409 | outside_messaging_window | Direct message outside Meta's window (24 hours after the person's last message, 7 days with HUMAN_AGENT); nothing was sent |
| 409 | recipient_unavailable | The person cannot receive messages from this account right now |
| 409 | sync_required | POST /inbox/conversations/{id}/sync before the account's conversations were synced |
| 409 | phone_number_not_registered | WhatsApp: register the number (POST /whatsapp/accounts/{id}/register) |
| 409 | APPROVAL_REQUIRED, ALREADY_PUBLISHED, NOT_EDITABLE, … | Post state conflicts |
| 410 | pending_expired | Pending connection expired or already completed |
| 429 | rate_limited | The platform rate-limited the request (Postgale's own key limit answers 429 without a code) |
| 400 | not_supported | The platform does not offer this feature |
| 400 | invalid_request | The platform rejected the input |
| 400 | template_error | WhatsApp: template name, language, parameters or status rejected by Meta |
| 403 | recipient_not_allowed, account_restricted | WhatsApp: recipient not in the test number's allowed list; WABA restricted or payment issue |
| 429 | marketing_limit | WhatsApp: Meta limits marketing messages to this person; retry later |
| 502 | platform_error | Any other platform failure |
For missing_permission, GET /accounts/{id}/health lists the account's missingPermissions and the features they block.
Platform-specific codes are listed in the WhatsApp, TikTok and
Meta Ads guides.
Rate limits
- 60 requests per minute per key by default; over the limit answers 429 (without a
code). The MCP server shares the same limit. - A platform's own rate limits answer 429 with
rate_limited. - Retrying
POST /postsis safe withx-request-id(Idempotency).