Errors - Polymorfa

Messaging and Platform API errors

Messaging and Platform API errors use this shape:

{
  "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:

{
  "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.