Skip to main content
EchoZero REST responses use a consistent envelope. MCP protocol errors use JSON-RPC 2.0 format on /mcp routes.

REST response envelope

Success

Paginated endpoints return data.items and data.pagination. See API conventions.

Error

Other examples of the same envelope:
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 an outcome 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 signRestRequest output for REST HMAC.
  • For inbound webhooks, check your canonical JSON against the test vectors and the public SDK source.
  • Check X-RateLimit-Remaining before bulk operations.
  • Use GET /status to verify OAuth tokens without hitting scoped routes.