Errors

Error shape

{
  "ok": false,
  "error": "Unauthorized"
}

Common examples

Most errors are single-field responses. These examples mirror the real API messages.

{
  "401_unauthorized": { "ok": false, "error": "Unauthorized" },
  "403_forbidden": { "ok": false, "error": "Forbidden" },
  "404_not_found": { "ok": false, "error": "Not found" },
  "406_not_acceptable": { "ok": false, "error": "Not acceptable" },
  "429_rate_limited": { "ok": false, "error": "Rate limited" }
}

How to fix errors

• 401 Unauthorized: your key is missing, revoked, or invalid. Double check the header and regenerate the key in Settings → Integrations.
• 403 Forbidden: the token is valid, but it is missing the required scope. Update the API key scopes or request a new OAuth token with the right scope.
• 406 Not acceptable: if you send an Accept header, it must include application/json.
• 429 Rate limited: slow down and retry with exponential backoff plus jitter.

Repeated unauthorized requests from the same IP are throttled for security. Wait a short time and try again, or switch to a valid key.

Rate limits and abuse

We apply default limits to keep the API stable for everyone. Limits can change as the API evolves, but these are the current defaults.

• 120 requests per minute per API key or OAuth token (most endpoints).
• 30 unauthorized attempts per minute per IP (missing or invalid key).

If you hit a limit you will receive 429. Retry with exponential backoff plus jitter.

Support email template

If you think you are blocked incorrectly or you need help diagnosing repeated 401/429 responses, email support@twentybaan.com with the template below. Do not include your raw API key.

Subject: Twentybaan API access help (401/403/429)

Account email:
Integration name (Zapier/Make/custom):
Endpoint(s) you called:
Approximate UTC timestamp:
HTTP status codes:
Notes (what you expected vs what happened):

Optional (helps us debug faster):
Your request id / correlation id (if you have one):
Your server public IP (if known):

Status codes

• 400 Bad request
• 401 Unauthorized
• 403 Forbidden
• 404 Not found
• 405 Method not allowed
• 406 Not acceptable
• 429 Rate limited

Accept header

If you send an Accept header, it must include application/json. Otherwise the API returns 406.