Skip to main content
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

StatusMeaning
200Request succeeded.
201Resource created (Create API key).
204Request succeeded; no body (Revoke API key).
400Request was syntactically valid but had no recognized fields, or contained an invalid filter value.
401Missing or malformed Authorization header, or the credential is invalid or revoked.
403Token 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.
404The resource referenced by the path does not exist within your organization.
422Body failed schema validation — see the per-field detail.
429The organization’s daily scan limit has been reached. The response detail is a structured object — see Rate limits below.
5xxTumban 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

StatusDetailWhere
401Missing or invalid Authorization header. Expected: Bearer <token>All authenticated endpoints.
401Token has expiredThe session token has expired.
401Invalid tokenThe session token failed verification.
401Invalid or revoked API keyThe sk_… token is unknown or revoked.
403Token missing org_id — make sure you have an active organization selectedDashboard session has no active org.
403API key management requires a dashboard session. API keys cannot revoke API keys.Revoke API key when called with sk_… auth.
403This endpoint requires a dashboard session. API keys are not permitted.Create API key, List API keys when called with sk_… auth.
403Admin role requiredUpdate org settings, Rotate webhook secret when the caller is a non-admin.
403This endpoint requires an admin dashboard session. API keys cannot access admin endpoints.Update org settings, Rotate webhook secret when called with sk_… auth.
422Invalid 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.
404Scan not foundGet scan.
404Batch not foundGet batch.
404Org settings not foundOrg settings endpoints.
404API key not found or already revokedRevoke API key.
400No fields to updateUpdate org settings.
400Invalid recommendation values: [...]List org scans.
429Structured 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.