# Errors & rate limits

Source: https://postgale.com/docs/api/errors

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](https://postgale.com/docs/api/authentication#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](https://postgale.com/docs/whatsapp#errors), [TikTok](https://postgale.com/docs/tiktok#errors) and
[Meta Ads](https://postgale.com/docs/ads#errors) guides.

## Rate limits

- 60 requests per minute per key by default; over the limit answers 429 (without a `code`). The [MCP server](https://postgale.com/docs/mcp) shares the same limit.
- A platform's own rate limits answer 429 with `rate_limited`.
- Retrying `POST /posts` is safe with `x-request-id` ([Idempotency](https://postgale.com/docs/api/posts#idempotency)).