Skip to content
Trace API & MCP Docs

Errors

The Trace API uses standard HTTP status codes. Any non-2xx response carries a JSON body describing what went wrong. This page lists the status codes you’ll see and the exact body shapes to parse.

Status codes

Section titled “Status codes”
Status Meaning When it happens
400 Bad request A malformed or invalid request that isn’t caught by parameter validation.
401 Unauthorized No credential supplied, or the API key is invalid, revoked, or expired.
402 Payment required Your org is out of credits (credit_exhausted). See Credits & usage.
403 Forbidden The credential is valid but not allowed here — e.g. an org key on a user-scoped endpoint (user_credential_required), a key with no org association, or an unverified email.
404 Not found The requested resource doesn’t exist (e.g. no company matches the identifier).
422 Unprocessable entity A query or path parameter failed validation (wrong type, out of range, etc.). This is FastAPI’s standard validation error.
429 Too many requests You hit the operational rate limit. Honor Retry-After and back off. See Credits & usage.
500 Internal server error An unexpected error on Trace’s side. Safe to retry after a short delay.

Error response shapes

Section titled “Error response shapes”

The API returns error bodies in two shapes depending on which layer rejected the request. Parse defensively: read error first, and handle it as either a string or an object.

Flat shape (auth, credit, and rate-limit errors)

Section titled “Flat shape (auth, credit, and rate-limit errors)”

Authentication, authorization, credit, and rate-limit failures return a flat object with a string error code and a human-readable message, plus context-specific fields:

{
  "error": "invalid_api_key",
  "message": "Invalid or revoked API key"
}

Common error codes in this shape:

error Status Meaning
authentication_required 401 No credential was supplied.
invalid_api_key 401 The API key is invalid, revoked, or expired.
user_credential_required 403 This endpoint needs a user-scoped key; an org key was used.
key_missing_org_association 403 The key has no org. Re-mint it from account settings.
email_verification_required 403 Verify your email before using the API.
credit_exhausted 402 Out of credits.
operational_rate_limit_exceeded 429 Too many requests.

Nested shape (resource errors)

Section titled “Nested shape (resource errors)”

Resource-level errors from the data endpoints — such as a company not found — return error as an object with code and message:

{
  "error": {
    "code": "company_not_found",
    "message": "No company found for 'not-a-real-domain.example'"
  }
}

Internal errors

Section titled “Internal errors”

Unhandled server errors on /v1 routes return a minimal body and never leak internal details:

{
  "error": "Internal server error"
}

Examples

Section titled “Examples”

402 — out of credits (flat shape, with credit context):

{
  "error": "credit_exhausted",
  "message": "Insufficient credits to complete this request.",
  "requested": 50,
  "shortfall": 12
}

429 — rate limited (flat shape; also sets the Retry-After and X-RateLimit-* response headers):

{
  "error": "operational_rate_limit_exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "retry_after_seconds": 30
}

403 — wrong credential class for a user-scoped endpoint (flat shape, with credential context):

{
  "error": "user_credential_required",
  "message": "This endpoint operates on user-scoped resources and requires a user-bound credential. Org-level and admin API keys cannot access it. Use a user-scoped API key (trace_…) or authenticate via the app.",
  "credential_type_used": "org_api_key",
  "credential_type_required": "user_api_key_or_jwt"
}

Next steps

Section titled “Next steps”