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.
{
"ok": false,
"code": "NOT_FOUND",
"message": "Tool not found",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}{
"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.