Errors - Brein

Brein uses one JSON error shape across the REST API. Branch on the machine-readable code, not on the human-readable message.

Error shape

{
  "statusCode": 422,
  "code": "VALIDATION_FAILED",
  "message": "The request contains a field value the server cannot accept.",
  "request_id": "a1b2c3d4",
  "retryable": false,
  "endpoint": "POST /api/v1/workspaces/acme/..."
}

Field	Meaning
`statusCode`	HTTP status.
`code`	Stable machine-readable code.
`message`	Human-readable context. It may change.
`request_id`	Include this when asking for help.
`retryable`	Whether the same operation may succeed later.
`endpoint`	Method and route that produced the error.

Common status codes

Status	Meaning	What to do
`400`	The request is invalid.	Fix the input before retrying.
`401`	The key or token is missing or invalid.	Reconnect or replace the credential.
`403`	The caller is authenticated but not allowed.	Check workspace membership and role.
`404`	The resource is not available to this caller.	Check the workspace and resource id.
`402`	The workspace has reached a commercial limit.	Show the usage response and the next action.
`409`	The resource changed or already exists.	Read the current state before retrying.
`429`	The request rate is too high.	Back off and follow the response guidance.
`500`	The server could not complete the request.	Preserve `request_id` when reporting it.