Errors

API errors will use consistent semantics across endpoints.

HTTP API errors use this response shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "category": "validation",
    "message": "Request validation failed.",
    "correlationId": "correlation-1234",
    "details": {
      "field": "from"
    }
  }
}

Error categories:

Category	Default code	Meaning
validation	VALIDATION_FAILED	Input failed validation.
authentication	AUTHENTICATION_FAILED	Authentication is missing or invalid.
authorization	AUTHORIZATION_FAILED	Authenticated caller lacks permission.
not_found	RESOURCE_NOT_FOUND	Requested resource does not exist or is not visible.
conflict	CONFLICT	Request conflicts with current state.
dependency_failure	DEPENDENCY_FAILURE	Required dependency failed or is unavailable.
decoder_failure	DECODER_FAILURE	Telemetry decoder failed safely.
internal	INTERNAL_ERROR	Unexpected server-side failure.

Error responses must include safe diagnostic details and correlation context without leaking secrets or cross-tenant information.

details values are limited to strings, numbers, booleans, and null. Details must not include passwords, tokens, raw credentials, raw payloads, secret configuration values, or data from another tenant or organization.

HTTP responses should include x-correlation-id when a correlation ID is available. Clients should include that value when reporting errors to support or operations.