Errors and limits
Common HTTP status codes
| Code | Meaning | Action |
|---|---|---|
401 | Missing or invalid auth | Check API key / JWT / share token |
403 | Forbidden for this workspace or brain | Verify X-Brain-Id and membership |
404 | Resource not found | Confirm IDs and slugs |
409 | Conflict (e.g. version mismatch) | Refetch and retry with latest version |
422 | Validation error | Fix request body per OpenAPI |
429 | Rate limited | Back off and retry with jitter |
5xx | Server error | Retry idempotent reads; avoid blind retries on writes |
SDK errors
The TypeScript client throws typed errors withstatus, code, and message. Handle 429 and transient 5xx with exponential backoff.
Details: Jobs and streaming — errors.
Rate limits
When you exceed plan limits, the API returns429. Reduce concurrency, cache reads, and prefer streaming only when needed.
Idempotency
- Reads (
GET, list, browse) — safe to retry. - Fire / mutate — use client-generated keys or check job status before re-firing duplicate work.
Auth failures
| Symptom | Check |
|---|---|
401 on all routes | Authorization: Bearer ak_live_... |
| Brain routes fail | X-Brain-Id header |
| Browser app fails | Publishable key + user JWT |