API troubleshooting

Problem

An API call fails and you need to know whether it is the key, the scopes, the URL or the payload.

How to check, in order

1. Call GET /me. A 200 proves the key, the header format and the base URL are all correct.
2. Compare the scopes it returns with the scope the endpoint requires.
3. Re-read the path: every v1 path starts with /api/public/v1, and ids are UUIDs.
4. For a 422, read the details array — it names the invalid fields.
5. For a 429, read Retry-After and back off.

How to fix

• 401 — fix the Authorization: Bearer … header, or the key was revoked or expired; create a new one.
• 403 insufficient_scope — create a key with the needed scope; scopes are fixed at creation.
• 404 — the id belongs to another workspace or was deleted.
• 409 idempotency_conflict — you reused an idempotency key with a different body.
• 500 — retry once with backoff, then send support the request id.

When to contact support

Persistent internal_error responses. Include the request id, the endpoint and the approximate timestamp.