/mcp routes.
REST response envelope
Success
data.items and data.pagination. See API conventions.
Error
error.field names the offending setting where the API can tell, for example on persona saves. Match on error.code and the HTTP status. The message text can change.
The code field is derived from the HTTP status:
Validation errors on 400 may include a comma-joined message from field validators.
Common HTTP statuses
Authentication errors
Inbound agent webhook errors return the same envelope with 401 for invalid
X-EZ-Signature or clock skew.
Rate limits
Authenticated requests include rate limit headers:Tiers
Rate limits apply per API key or OAuth user id.
MCP JSON-RPC errors
MCP routes (POST /mcp, GET /mcp/sse) return JSON-RPC errors instead of the REST envelope:
MCP session errors
Signal ingestion outcomes
Inbound signal webhooks return 200 with anoutcome field even when no trade executes:
The response can also carry
rejection (why a caption you wrote was not published) and executionResult (when execution completed). All of these come back with HTTP 200, so check outcome.
Treat skipped, unmatched and failed as non-retryable unless you change the payload.
Signal validation errors (HTTP 400)
skipReason dictionary (selected)
Execution error tags (in executionResult.errorMessage)
The list above is a selection. New
skipReason values can be added without notice (see the versioning policy), so treat an unknown reason as non-retryable and log it. A full public registry is not published yet.
Retry guidance
Debugging tips
- Compare your string-to-sign against the SDK’s
signRestRequestoutput for REST HMAC. - For inbound webhooks, check your canonical JSON against the test vectors and the public SDK source.
- Check
X-RateLimit-Remainingbefore bulk operations. - Use
GET /statusto verify OAuth tokens without hitting scoped routes.