Errors#
Every error response carries a stable, machine-readable error code and a
human-readable message:
{ "status": "error", "error": "invalid_api_key", "message": "Invalid API key." }
Match on error, not on the message text — messages may be reworded, codes won't.
Current error codes#
These are the codes reachable through the endpoints that exist today:
error |
Status | Likely cause | Fix |
|---|---|---|---|
invalid_api_version |
400 | Unsupported X-Api-Version (below minimum, above latest, or malformed CalVer) |
Send a valid YYYY.M.MICRO version in [minimum, latest], or omit the header to use latest (see Authentication) |
missing_parameter |
400 | Authenticating with a user token but organization_id is absent |
Add ?organization_id=<id> (see Authentication) |
invalid_api_key |
401 | Missing or unrecognized Bearer credential (service key or user token) | Check Authorization: Bearer <...>; for a user token confirm it is valid |
insufficient_permissions |
403 | Valid user token, but the user is not a member of the requested organization | Use an organization_id the user belongs to |
unknown_provider |
404 | The provider name in the URL isn't a registered provider | Check the spelling against GET /api/v1/providers |
service_unavailable |
503 | A dependency (Mongo, Redis, or the TeamBoost platform API) is temporarily unreachable | Retry with backoff; check /health/ready |
More codes arrive with features
The error envelope already reserves codes for capabilities that aren't built
yet — for example webhook signature failures (invalid_signature) and job
state errors (invalid_job_state). They become reachable as those features
ship; see the Roadmap.