Spur MCP error contracts
Tool failures return rich structured payloads so agents and operators can diagnose and recover faster.
Top-level error envelope
- ok: false
- statusCode
- message
- providerError
- hints[]
- raw
- traceId
Provider passthrough fields
- message
- type
- code
- error_subcode
- error_user_title
- error_user_msg
- fbtrace_id
- is_transient
- error_data.details
Built-in hint mappings
error_subcode: 2388124
Meta edit cooldown is active. Retry template submission after 24 hours.
error_subcode: 2388047
Template body format is invalid. Avoid more than two consecutive line breaks.
error_subcode: 2388153
Button text mismatch. Align payload button text with approved template text.
error_user_title: WhatsApp Store not configured
Configure WhatsApp Store flow and flow_id before submitting flow buttons.
statusCode: 401
Use a valid Bearer API key for the target workspace.
statusCode: 409 or duplicate message
Contact already exists. Search and update instead of creating again.
Example failure payload
{
"isError": true,
"structuredContent": {
"ok": false,
"statusCode": 400,
"message": "Template body format is invalid",
"providerError": {
"message": "(#100) Invalid parameter",
"type": "OAuthException",
"code": 100,
"error_subcode": 2388047,
"error_user_title": "Template body issue",
"error_user_msg": "Remove consecutive line breaks in template body.",
"fbtrace_id": "A1BCDefGhIJK",
"error_data": {
"details": "body has invalid formatting"
}
},
"hints": [
"Template body format invalid. Remove more than two consecutive line breaks.",
"Share fbtrace_id (A1BCDefGhIJK) with support for escalation."
],
"traceId": "A1BCDefGhIJK"
}
}