/v1 API can return GatewayError, ValidationError or MetaError. Graph-compatible routes can return Meta’s original GraphError body and status. Do not use one parser for both interfaces.
Common statuses include 401 for invalid keys, 402 for payment, 404 for missing or unowned resources, 409 for conflicts, 422 for core validation, 429 for limits and 503 for a paused or unconfigured gateway. Check each operation’s reference.
Avoid duplicate sends
unknown_outcome means a send may already have happened. Check status events and message history before retrying. A timeout or server error does not prove that nothing happened.
For 429, honor Retry-After when present. Use bounded retries and backoff; do not assume a universal account quota.
Diagnose safely
GET /v1/logs filters origin (api, meta, webhook) and errors (errors=1 or errors=true). The contract describes up to 200 entries retained for seven days; bodies are not logged.
For a gateway 500 with requestId, give that ID to support, not API keys or customer message contents.