Start with the HTTP status, structured error code, and meta.requestId. Never include a bearer
credential, webhook secret, upload intent, or unredacted customer payload in a support request.
| Symptom | Likely cause | What to verify |
|---|---|---|
401 invalid_token |
Missing, expired, revoked, or malformed credential | Secret source, rotation state, Authorization header |
403 insufficient_scope |
Credential lacks an operation scope | Required and conditional scopes in the operation reference |
403 forbidden |
Workspace, role, grant, plan, or sharing policy denied access | Principal ownership and resource grants |
404 not_found |
Wrong opaque ID or resource is intentionally invisible | Workspace boundary, resource lifecycle, exact ID |
409 idempotency_conflict |
One key was reused with different input | Original request fingerprint and retry code |
409 conflict |
Current resource state rejects the action | Lifecycle state and latest resource |
412 precondition_failed |
The supplied revision is stale | Re-read, merge deliberately, send the new ETag |
428 precondition_required |
A guarded write omitted If-Match |
Read the resource before writing |
429 rate_limit_exceeded |
Current credential or source exceeded its bucket | Retry-After and rate-limit headers |
502–504 |
A cell-local dependency is temporarily unavailable | Request ID, status page, bounded safe retry |
Region and endpoint checks
Official clients derive the regional endpoint from the credential. For direct HTTP integrations,
send German credentials to https://api.de.teamgrid.app/v1 and United States credentials to
https://api.us.teamgrid.app/v1. Do not follow a redirect with an Authorization header.
Safe diagnostic sequence
- Call
GET /workspacewith the same credential and endpoint. - Confirm the operation’s required and conditional scopes.
- Remove optional filters and retry one bounded read.
- For a write, obtain the latest resource revision and keep the same idempotency key.
- Record the response status, error code, request ID, time, and regional endpoint.
For CLI authentication, run teamgrid auth status --check. A support report may include the
profile name, region, cell, credential ID, authentication source, scopes, expiry, CLI version,
Node.js version, operating system, structured error code, and request ID. It must not include a
credential, environment dump, browser approval URL, authorization code, PKCE verifier, keychain
export, customer response body, or unredacted terminal transcript. See
authentication by environment.
The errors and rate limits guide defines retry behavior. For platform-wide availability, check TeamGrid Status.