> ## Documentation Index > Fetch the complete documentation index at: https://docs.tumban.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors > HTTP status codes returned by the Tumban API. The Tumban API uses standard HTTP status codes. Failures return a JSON body with a `detail` field; validation errors include a list of field-level reasons. ## Status codes | Status | Meaning | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Request succeeded. | | `201` | Resource created (Create API key). | | `204` | Request succeeded; no body (Revoke API key). | | `400` | Request was syntactically valid but had no recognized fields, or contained an invalid filter value. | | `401` | Missing or malformed `Authorization` header, or the credential is invalid or revoked. | | `403` | Token decoded but lacks the required organization context, **or** the role is insufficient (some endpoints are admin-only), **or** API-key auth was used on an endpoint that requires a dashboard session. | | `404` | The resource referenced by the path does not exist within your organization. | | `422` | Body failed schema validation — see the per-field detail. | | `429` | The organization's daily scan limit has been reached. The response `detail` is a structured object — see [Rate limits](#rate-limits) below. | | `5xx` | Tumban server error. Retry with backoff. | ## Error envelope Most errors: ```json theme={null} { "detail": "Invalid or revoked API key" } ``` Validation errors (`422`) — `detail` is a list. Each entry follows the underlying validation library's native shape: `loc` (an array of segments locating the offending field), `msg`, `type`, and may include `input`, `ctx`, and `url`. ```json theme={null} { "detail": [ { "loc": ["body", "profile_url"], "msg": "Input should be a valid URL", "type": "url_parsing", "input": "not-a-url" } ] } ``` Use `loc` to locate the field — the last segment is the field name. ## Common detail strings | Status | Detail | Where | | ------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | `Missing or invalid Authorization header. Expected: Bearer ` | All authenticated endpoints. | | 401 | `Token has expired` | The session token has expired. | | 401 | `Invalid token` | The session token failed verification. | | 401 | `Invalid or revoked API key` | The `sk_…` token is unknown or revoked. | | 403 | `Token missing org_id — make sure you have an active organization selected` | Dashboard session has no active org. | | 403 | `API key management requires a dashboard session. API keys cannot revoke API keys.` | [Revoke API key](/api/keys/revoke) when called with `sk_…` auth. | | 403 | `This endpoint requires a dashboard session. API keys are not permitted.` | [Create API key](/api/keys/create), [List API keys](/api/keys/list) when called with `sk_…` auth. | | 403 | `Admin role required` | [Update org settings](/api/org/update-settings), [Rotate webhook secret](/api/webhook-secret/rotate) when the caller is a non-admin. | | 403 | `This endpoint requires an admin dashboard session. API keys cannot access admin endpoints.` | [Update org settings](/api/org/update-settings), [Rotate webhook secret](/api/webhook-secret/rotate) when called with `sk_…` auth. | | 422 | `Invalid callback URL: ` | [Update org settings](/api/org/update-settings) when `default_callback_url` fails the safety check. `` varies: disallowed scheme, missing host, DNS-resolution failure, or a private/internal/reserved address. | | 404 | `Scan not found` | [Get scan](/api/scans/get). | | 404 | `Batch not found` | [Get batch](/api/scans/batch-get). | | 404 | `Org settings not found` | Org settings endpoints. | | 404 | `API key not found or already revoked` | [Revoke API key](/api/keys/revoke). | | 400 | `No fields to update` | [Update org settings](/api/org/update-settings). | | 400 | `Invalid recommendation values: [...]` | [List org scans](/api/org/list-scans). | | 429 | Structured object — see [Rate limits](#rate-limits). | [Create scan](/api/scans/create), [Create batch](/api/scans/batch) when the org's `daily_scan_limit` is exhausted. | ## Rate limits When the organization's `daily_scan_limit` is exceeded, scan-submission endpoints return `429` with a JSON object (not a string) under `detail`: ```json theme={null} { "detail": { "error": "daily_scan_limit_exceeded", "limit": 1000, "used": 1000 } } ``` * `error` — always `daily_scan_limit_exceeded` for this case. * `limit` — the org's configured cap. * `used` — scans counted against the cap so far today (UTC day, rolls over at `00:00 UTC`). [Create batch](/api/scans/batch) has a partial-acceptance path: if the batch is larger than the remaining budget, the request succeeds with the first N profiles accepted and the response sets `daily_limit_truncated` and `profiles_skipped`. Only a fully-rejected batch (zero capacity remaining) returns `429`. Tumban does **not** return `X-RateLimit-*` headers or accept an `Idempotency-Key` header. Plan retries around the `429` body shape above.