Exhibit A
Find the one field support will ask for
{"error": {"message": "(#131000) Something went wrong","type": "OAuthException","code": 131000,"error_data": {"messaging_product": "whatsapp","details": "Message failed to send due to an unknown error."},"fbtrace_id": "AhR7mQ2xKpV9cLwT3nY0sZb"}}
Field 5: error.fbtrace_id — Unique to this one request. Paste it into the support ticket with the UTC time it happened.
What is the fbtrace_id?
The FB Trace ID (fbtrace_id) is a short opaque string that the Graph API includes in the error object of a failed response, alongside message, type, code and error_subcode. Meta describes it as an internal support identifier: when you report a problem with a Graph API call, the fbtrace_id lets Meta's engineers find the log data for that specific request. It works the same way across Graph API products, including the WhatsApp Cloud API and the WhatsApp Business Management API.
The value is unique to one request and means nothing on its own: you can't decode it or look it up yourself, and a retry of the same payload gets a new one. Graph API responses also usually carry trace headers such as x-fb-trace-id, which help when a call fails without a readable JSON body. Neither is a message identifier. The WAMID returned by a successful send is what identifies a WhatsApp message, and it is the key that every status webhook refers back to.
That difference decides what you hand to support. For a synchronous failure, such as a send rejected with error 100 (Invalid Parameter), an expired token or a template mismatch, the fbtrace_id points straight at the failing call. For an asynchronous failure, such as a message accepted and later reported failed with error 131026 (Message Undeliverable), the webhook's errors array has no fbtrace_id; support needs the WAMID, the phone number ID and the timestamps instead.
Key takeaways
- The fbtrace_id is an opaque ID Meta attaches to a Graph API error so its engineers can find that exact request in their logs.
- It identifies one API call; a WAMID identifies one WhatsApp message across its whole lifecycle.
- Log it with every failed call, together with the error code, subcode, UTC timestamp and your own request ID.
- Put it in Meta support tickets: it turns “sends are failing” into a request that can be traced on first read.
- Status-webhook errors carry no fbtrace_id; for asynchronous failures give support the WAMID and timestamp instead.
The fbtrace_id in code
{"error": {"message": "(#131000) Something went wrong","type": "OAuthException","code": 131000,"error_data": {"messaging_product": "whatsapp","details": "Message failed to send due to an unknown error."},"fbtrace_id": "AhR7mQ2xKpV9cLwT3nY0sZb"}}
How does the fbtrace_id work?
Every call gets a trace
Meta assigns each Graph API request a trace identifier on its side, whether the call succeeds or fails.
On failure, read the error object
The response body's
error.fbtrace_idsits next to the code, subcode and message. HTTP status codes alone don't carry it.Log it with context
Store the trace ID with a UTC timestamp, the endpoint, the phone number ID or WABA ID, your own job ID and the error code, as structured logging fields you can search. Never log the access token with it.
Escalate with it
When a failure needs Meta's help, open a ticket through Meta Direct Support or your provider with several trace IDs, the exact error text and when it happened.
For async failures, use the WAMID
Failed status webhooks carry no trace ID. Give support the message ID, the recipient's country and the time of the failed status instead.
Why does the fbtrace_id matter?
Support tickets without identifiers are slow: “some messages failed yesterday” forces Meta, or your provider, to ask for examples before anyone can look. A ticket with three trace IDs, their timestamps and the error codes can be traced on first read. Logging the ID costs one field per failed request, and it is often the only way to establish whether a failure happened inside Meta's platform or in your own code.
Example: A support ticket that got answered, Kolkata
A Kolkata logistics company sees a burst of error 131000 (“Something went wrong”) on template sends between 14:05 and 14:20 IST. Instead of reporting that WhatsApp is failing, the developer filters the logs by error code and attaches five trace IDs with UTC timestamps, the phone number ID and one request body with the customer's number masked. Support can locate the requests from the trace IDs and confirms a transient platform issue in that window, so the team replays the affected sends from its queue instead of rewriting code that was never broken.
Common mistakes with the fbtrace_id
Not logging it
The ID exists only in the response you received. If your logger drops the error body, it is gone, and support has to start from your description.
Confusing it with the WAMID
The trace ID describes a request; the WAMID describes a message. Sending a WAMID where a trace was needed, or the reverse, sends support to the wrong logs.
Reporting a pattern with one example
A single trace can look like noise. For a recurring problem, include several trace IDs with timestamps, the error text and how often it happens.
Pasting secrets along with it
Tickets with full curl commands often include the access token and customers' numbers. Mask both; the trace ID is enough to find the call.
Waiting weeks to report
Logs aren't kept indefinitely, so an old trace may no longer be retrievable. Escalate while the failure is fresh.
Best practices for the fbtrace_id
- Index the trace ID in your log search so you can jump from a ticket to the request in seconds.
- Record times in UTC and say so in the ticket.
- Attach the request body with personal data masked, plus the endpoint and Graph API version.
- Keep a “last 20 failures” view per error code with trace IDs ready to copy.