Errors

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 below.
`5xx`	Tumban server error. Retry with backoff.

Error envelope

Most errors:

{ "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.

{
  "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 <token>`	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 when called with `sk_…` auth.
403	`This endpoint requires a dashboard session. API keys are not permitted.`	Create API key, List API keys when called with `sk_…` auth.
403	`Admin role required`	Update org settings, Rotate webhook secret when the caller is a non-admin.
403	`This endpoint requires an admin dashboard session. API keys cannot access admin endpoints.`	Update org settings, Rotate webhook secret when called with `sk_…` auth.
422	`Invalid callback URL: <reason>`	Update org settings when `default_callback_url` fails the safety check. `<reason>` varies: disallowed scheme, missing host, DNS-resolution failure, or a private/internal/reserved address.
404	`Scan not found`	Get scan.
404	`Batch not found`	Get batch.
404	`Org settings not found`	Org settings endpoints.
404	`API key not found or already revoked`	Revoke API key.
400	`No fields to update`	Update org settings.
400	`Invalid recommendation values: [...]`	List org scans.
429	Structured object — see Rate limits.	Create scan, Create 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:

{
  "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 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.

Get started

Core concepts

API reference

Webhooks

Reference

Status codes

Error envelope

Common detail strings

Rate limits

​Status codes

​Error envelope

​Common detail strings

​Rate limits

Status codes

Error envelope

Common detail strings

Rate limits