Troubleshooting

Common failures and fixes.

401 Unauthorized

Verify the API key prefix, that the key is active, and the Authorization header format. Runtime keys belong on Fly. Org API keys belong on platform.intertrace.ai control-plane routes; mixing them is a 401. Authentication.

426 ITR_UPGRADE_REQUIRED (coding-agent hooks)

Your itr is too old. Hooks no longer ask the dashboard; they ask the gateway (POST /v1/actions/authorize) with this device's runtime key. Until you upgrade, hooks fail closed and only workspace reads go ahead. Update itr, run itr login and itr connect, then check with itr doctor.

422 Validation

Compare your payload to the event schema page; ensure ISO timestamps and span kinds.

Traces not appearing

Confirm the org API key belongs to the organization you are viewing and that ingestion returned 201 (or 200 for a replayed Idempotency-Key). A 422 response body lists the fields that failed validation.