Skip to API content
Birdor API v1

API reference · v1

Error handling

Read the HTTP status first, then inspect the response body and request identifier.

Error format

Public validation and application errors share the Birdor envelope with ok, code, message and request_id. Validation details include only field paths and codes.

Application error
{
  "ok": false,
  "code": "NOT_FOUND",
  "message": "Tool not found",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
Parameter validation error
{
  "ok": false,
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}

Status guide

400
Invalid parameters, JSON or Turnstile verification; stream read failure returns INVALID_REQUEST_BODY before admission. Read deadlines/caller abort return 408, oversized bodies 413, query overflow 414.
404
Unknown route, missing tool, or no matching tool IDs.
429
Ingress, workspace/actor minute, monthly quota or separate waitlist limit reached. Inspect the code and Retry-After; waitlist RATE_LIMITED may omit it.
500
Server failure; missing waitlist database configuration returns 500. Storage/deadline failures return 503 and may have partial or late effects; preserve the original trace.

Retries & limits

Fix 400 inputs; 401 requires a valid credential and 403 requires access. Ingress, workspace/actor minute, monthly quota and waitlist limits are separate. Inspect 429 code/Retry-After; legacy waitlist RATE_LIMITED can omit it. Quota headers appear only after credentialed admission. Each admitted catalog request costs one unit, including business errors; retries are new admissions. A catalog 503 may retain a pending reservation: inspect the original trace/log before retrying. Waitlist 503 can mean a saved subscription and failed or late qualification; retry uses email deduplication/upsert and new limits. No general Idempotency-Key replay or automatic rollback is promised.