Introduction
Errors
Failed responses use a shared JSON envelope so clients can branch on error.code.
{
"error": {
"code": "NOT_FOUND",
"message": "Location was not found.",
"details": {}
}
}HR may also include request_id.
Common codes
| HTTP | error.code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Malformed request |
| 401 | UNAUTHORIZED | Missing or invalid JWT |
| 403 | FORBIDDEN | Authenticated but not permitted |
| 404 | NOT_FOUND | Resource missing (or a *_NOT_FOUND variant) |
| 409 | CONFLICT | Version, state, or idempotency conflict |
| 422 | VALIDATION_ERROR | Body or organisation bootstrap failed |
| 500 | INTERNAL | Unexpected server error |
Service-specific codes include VERSION_CONFLICT, INVALID_STATE_TRANSITION, CERTIFICATION_EXPIRED, and PLANNING_FAILED. The OpenAPI spec for each Worker lists the codes that route can return.
Idempotency
Creates and some mutations accept Idempotency-Key. Replaying the same key returns the original result or IDEMPOTENCY_CONFLICT if the payload differs.