> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Messaging and Platform API error envelopes and HTTP status semantics.

## Messaging and Platform API errors

Messaging and Platform API errors use this shape:

```json theme={null}
{
  "error": "human-readable safe message",
  "docs": "https://docs.polymorfa.com/api/example"
}
```

`docs` is optional. Error responses do not include separate `code`, `message`,
`details`, or `request_id` JSON fields. Use the `X-Request-Id` response header
for correlation and branch primarily on HTTP status plus the documented
operation response.

| Status | Meaning                                                                             |
| -----: | ----------------------------------------------------------------------------------- |
|  `400` | Invalid body, parameter, version, or state requested by the caller                  |
|  `401` | Missing, malformed, expired, revoked, or otherwise invalid credential               |
|  `402` | An entitlement or funded capability is required                                     |
|  `403` | Valid principal without the required scope, role, project ownership, or client rule |
|  `404` | Resource absent or intentionally hidden by tenant/project isolation                 |
|  `409` | Conflicting state transition or unique resource                                     |
|  `429` | Organization request window exceeded                                                |
|  `500` | Unexpected service failure                                                          |
|  `501` | Explicitly unimplemented native operation                                           |

Error responses use these documented shapes and do not expose underlying
service details.

## Meta-compatible errors

Meta-compatible Messaging API routes reshape failures into Meta's envelope:

```json theme={null}
{
  "error": {
    "message": "…",
    "type": "GraphMethodException",
    "code": 100,
    "error_subcode": 0,
    "error_data": { "messaging_product": "whatsapp", "details": "…" },
    "fbtrace_id": "…"
  }
}
```

Use `fbtrace_id` for correlation. Unsupported backend capabilities also return
a Meta-shaped error, so existing Cloud API clients can keep their error logic.

## Retry guidance

* Fix the request before retrying `400`, `401`, `403`, `404`, or `409`.
* Retry `429` only after `Retry-After`.
* Retry a bounded number of `500` responses with exponential backoff and
  jitter; include `X-Request-Id` or `fbtrace_id` in support requests.
* Treat `501` as a feature boundary, not a transient outage.