Errors

Audience

Integrators handling API error responses in automation and retry logic.

HTTP status codes

Status	Meaning
400	Malformed request
401	Missing, invalid, or revoked API key
402	Insufficient org credits for an assessment
403	Not permitted (missing scope, billing gate)
404	Resource unknown or not visible to your key
409	State conflict (duplicate upload, artifact cited by assessment)
422	Request body failed validation
429	Rate limit (authentication flows only — see below)
503	Service temporarily unavailable

Errors return JSON with a message field. Use the HTTP status and message in your automation — you do not need to parse internal type names.

Troubleshooting matrix

Symptom	Status	Likely cause	Fix
Invalid key	401	Revoked, wrong, or malformed Authorization header	Check secret; mint new key in portal
Missing scope	403	Key lacks scope for route	New key with scope from Authentication
Project not found	404	Wrong projectPid or key for different domain	GET /domains/<domainPid>/projects; confirm domain
Slug lookup fails	404	Wrong slugs or project outside key domain	Use pid listing instead — Concepts
Out of credits	402	Org credit balance exhausted	Show the recovery string — Credits and feedback
Duplicate upload	409	Reused storage key on complete	Re-run upload-init and PUT
Cannot delete artifact	409	Cited by an assessment	POST .../archive instead
Validation error	422	Wrong field types or missing required fields	Compare body to API reference
Auth rate limit	429	Too many login/OTP attempts	Wait retryAfter seconds (portal flows only)
Service down	503	Temporary outage	Exponential backoff and retry

Not found vs forbidden

Many routes return 404 when a resource exists but is outside your API key's domain, rather than 403. This avoids revealing whether a resource exists.

Retry guidance

Status	Retry?
401, 403, 404, 409, 402, 422	No — fix credentials, scopes, or request body
429	Yes — wait at least retryAfter seconds
503	Yes — exponential backoff

Rate limits

Integrator API calls (bearer key on domains, projects, assessments, uploads, search) are not rate-limited today. Use reasonable poll intervals — see Async jobs.

Rate limiting applies to portal authentication (login, OTP, password reset). Integrators using API keys do not hit these limits in normal operation.

When 429 occurs (typically portal flows):

{
  "message": "Too many authentication attempts",
  "retryAfter": 60
}

retryAfter is in seconds. Per-key API rate limits may be introduced later; this page and the changelog will be updated.

Example error bodies

401

{
  "message": "Invalid authentication state"
}

403 (missing scope)

{
  "message": "API key missing required scope: projects:write"
}

402

InsufficientCreditsError and TrialExpiredError both carry a required recovery field naming the next step. Display it verbatim rather than composing your own wording — it is the same sentence the AIR web app shows, so a person who reads it in your client and then opens the portal gets one consistent instruction.

{
  "_tag": "air/InsufficientCreditsError",
  "orgPid": "org_…",
  "available": 0,
  "required": 1,
  "recovery": "Request more assessment credits from Thalus, or buy a 5-credit pack to continue now."
}

To act on it, see Credits and feedback — read the balance before you spend, request credits, or hand a person a purchase link.

Related

• Authentication — scopes and domain scoping
• Async jobs — polling without hammering the API
• Concepts — Billing — credits and assessments
• API reference — per-endpoint error codes