Errors

All API errors follow a consistent JSON format. Use the code field for programmatic handling and the message field for human-readable context.

Error Response Format


{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Description of what went wrong",
    "status": 400
  }
}

Some errors include additional detail in a fields object for programmatic handling.

Error Codes

Code	HTTP Status	When it occurs
`BAD_REQUEST`	400	Invalid JSON, missing required fields, invalid enum values, or trying to PATCH status directly
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Valid key but insufficient scopes, agent attempting a `done` transition the workspace disallows, or agent attempting to reopen a `done`/`canceled` task
`NOT_FOUND`	404	Resource doesn’t exist or doesn’t belong to your workspace
`CONFLICT`	409	Operation conflicts with current state
`INVALID_TRANSITION`	422	Status transition not allowed by the state machine
`INTERNAL_ERROR`	500	Unexpected server error

Error responses follow the format shown above. Use the code field for programmatic handling.

Valid Enum Values

For reference, here are all valid enum values used across the API:

Task Status

backlog, todo, in_progress, waiting, done, canceled

Task Priority

p0, p1, p2, p3

Task Effort

xs, s, m, l, xl

Project Status

not_started, planning, in_progress, blocked, complete, canceled

Initiative Status

planned, active, paused, completed, canceled