Observability

Last updated Jun 14, 2026

Every request carries a X-Request-Id response header and a matching request_id on the problem object for errors. Use it as the primary handle when debugging or opening a support ticket.

Request-ID propagation

HTTP/1.1 202 Accepted
X-Request-Id: req_Qw9xYz8A

• On a 2xx response, capture the header and log it alongside your business trace.
• On a non-2xx, it's also in the RFC 7807 request_id field.

On Events and AuditEntries, request.id is the same ID — you can cross-reference a webhook to the original POST.

GET /v1/requests/{id}

Matter retains each request — captured body, response, and actor — for 7 days by default. Retrieval:

curl https://api.mattermode.com/v1/requests/req_Qw9xYz8A \
  -H "Authorization: Bearer $MATTER_KEY"

Returns:

{
  "id": "req_Qw9xYz8A",
  "object": "request",
  "method": "POST",
  "path": "/v1/entities",
  "status": 202,
  "idempotency_key": "7a0c3b8e-...",
  "actor": {"type": "agent", "id": "agt_Nq3KcAbc"},
  "authorized_by": {"human_principal_id": "usr_...", "agent_id": "agt_..."},
  "request_body": { /* captured */ },
  "response_body": { /* captured */ },
  "occurred_at": 1745251200,
  "livemode": true
}

Secrets (Authorization headers, sensitive fields) are redacted.

Dashboard deep-links

The Matter dashboard at https://mattermode.com/dashboard supports deep-links to individual requests, entities, filings, and events:

• https://mattermode.com/dashboard/requests/req_Qw9xYz8A
• https://mattermode.com/dashboard/entities/ent_Nq3KcAbc
• https://mattermode.com/dashboard/filings/flg_Ab1

Log these links in your application alongside the IDs so operators can jump straight from log entry to the Matter UI.

Logging recommendations

At minimum, log on every API call:

• request_id
• HTTP status
• The code from any error response
• Idempotency key (helpful for retry troubleshooting)

Structured logs make cross-correlation trivial:

{
  "timestamp": "2026-05-01T14:00:00Z",
  "level": "info",
  "msg": "matter_api_call",
  "path": "/v1/entities",
  "method": "POST",
  "status": 202,
  "request_id": "req_Qw9xYz8A",
  "idempotency_key": "7a0c3b8e-...",
  "entity_id": "ent_Nq3KcAbc",
  "dashboard_url": "https://mattermode.com/dashboard/requests/req_Qw9xYz8A"
}

Support tickets

When opening a ticket at support@mattermode.com, include:

• request_id of the problematic call.
• The value of code from the error.
• What you expected vs what happened.

Because Matter retains the request body and response for 7 days, support can reproduce any issue with zero extra information.

Error budgets and SLOs

Matter targets:

• 99.9% availability on synchronous endpoints.
• 99.5% delivery within 24 hours for asynchronous filings.
• 99.9% webhook delivery within 3 days.

Monitoring is at https://status.mattermode.com. Subscribe to incidents via the status page.