Errors

The Hoursmith API uses a consistent error envelope with stable codes. Learn the format, status codes, and how to handle each.

Every error response uses the same JSON envelope, so you can handle failures predictably.

Error format

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "fields": { "name": "required" }
  }
}

code — a stable, machine-readable string. Branch your logic on this, not on message.
message — a human-readable description (may change wording over time).
fields — present only on validation errors; maps each invalid field to a reason.
On forbidden_plan, the error also includes requiredPlan and feature.

HTTP	`code`	Meaning	What to do
`400`	`bad_request`	Malformed request.	Fix the request.
`401`	`unauthenticated`	Missing/invalid/revoked token.	Check the `Authorization` header.
`402`	`forbidden_plan`	Workspace lacks API access.	Upgrade to Studio/Agency.
`403`	`forbidden_scope`	Role can't perform this action.	Use a token with a higher role.
`404`	`not_found`	Record doesn't exist or isn't visible to you.	Verify the id and access.
`409`	`conflict`	Blocked by state.	See below.
`422`	`validation_error`	Invalid input (or missing `Idempotency-Key`).	Inspect `fields`.
`429`	`rate_limited`	Too many requests.	Respect `Retry-After`.
`500`	`internal`	Something went wrong on our side.	Retry with backoff; contact support if it persists.