Meta API Error Reference

Error Object Format

Most API failures return an error object with this shape:

{
  "error": {
    "message": "<ERROR_MESSAGE>",
    "type": "<ERROR_TYPE>",
    "code": 190,
    "error_subcode": 1234567,
    "error_data": {
      "details": "<OPTIONAL_DETAILS>"
    },
    "fbtrace_id": "<TRACE_ID>"
  }
}

Always log: error.code, error_subcode, error.message, error_data.details, and fbtrace_id.

Authentication and Permission Errors

HTTP	Code	Meaning	Recommended action
`401`	`190`	Access token invalid/expired	Refresh/reconnect token
`403`	`10`	App permission denied	Verify app permissions and review status
`403`	`200`	Business asset permission missing	Reassign Business Portfolio permissions

Request Validation Errors

HTTP	Code	Meaning	Recommended action
`400`	`100`	Invalid parameter	Validate payload schema
`400`	`131008`	Required parameter missing	Add missing field
`400`	`131051`	Unsupported message type	Fix message `type` and object structure
`400`	`132000`	Template parameter mismatch	Align variables with approved template
`400`	`132001`	Template not found/unavailable	Use exact approved template name + language

Delivery and Policy Errors

HTTP	Code	Meaning	Recommended action
`400`	`470`	Outside service window	Send approved template first
`400`	`131026`	Message undeliverable	Validate destination and retry when appropriate
`429`	`131056`	Pair rate limit reached	Slow down per-recipient pace
`429`	`130429`	Throughput limit hit	Queue/throttle traffic and retry with backoff

Platform and Throttling Errors

HTTP	Code	Meaning	Recommended action
`429`	`4`	Too many API calls	Back off and retry with jitter
`500`	`2`	Temporary service issue	Retry with exponential backoff
`503`	`131016`	Service unavailable	Retry with backoff and circuit-breaker guard

Error Handling Strategy

Retryable:

429 rate limits
500 / 503 server-side failures
Network timeout/connectivity errors

Usually non-retryable without payload/access changes:

100 validation errors
10/200 permission errors
132000/132001 template errors
470 policy window violations

Suggested Retry Policy

Use exponential backoff with jitter.
Cap retry attempts for transient classes (3–6 attempts).
Send non-retryable errors directly to a dead-letter/ops queue.
Include idempotency keys in sender jobs to avoid duplicate sends.
Always store fbtrace_id for support escalation.

Dualhook surfaces webhook-side delivery errors and management alerts in monitoring views. Message-send API failures happen in your backend caller and should be logged there with full Graph error metadata.