Diagnostics

Diagnostic codes are stable, structured errors and warnings. API errors, ingest partial-success responses, and logs use the same registry.

Ingest

Code	Name	Severity	HTTP	Meaning
ORL-1001	IngestTokenInvalid	error	401	Missing or invalid ingest token.
ORL-1002	IngestTokenRevoked	error	401	Token revoked or expired.
ORL-1003	IngestSignalNotPermitted	error	403	Signal not permitted by token.
ORL-1004	IngestRequestTooLarge	error	413	Request exceeds size or row limits.
ORL-1005	IngestEnvUnresolved	error	400	Environment unresolved.
ORL-1006	IngestEnvCapExceeded	error	400	Environment cap exceeded.
ORL-1007	IngestEnvConflict	warn		Resource environment conflicts with token pin.
ORL-1008	IngestUnsupportedEncoding	error	415	Unsupported content type or encoding.
ORL-1009	IngestLimitClamped	warn		Attribute or body limits clamped.
ORL-1010	IngestSeriesCapExceeded	error	400	Metric series cap exceeded.
ORL-1011	IngestTimestampOutOfRange	error	400	Timestamp outside acceptance window.
ORL-1012	IngestBackpressure	error	503	Backpressure shed; retry advised.
ORL-1013	IngestMalformed	error	400	Malformed OTLP payload or identifier.

Query

Code	Name	Severity	HTTP	Meaning
ORL-2001	QuerySyntaxError	error	400	OQL syntax error with position.
ORL-2002	QueryUnknownField	error	400	Unknown or type-ambiguous field.
ORL-2003	QueryUnknownFunction	error	400	Unknown function or wrong arity.
ORL-2004	QueryScanBudgetExceeded	error	422	Query exceeds scan budget.
ORL-2005	QueryTimeout	error	504	Query execution timeout.
ORL-2006	QueryResultTruncated	warn		Result truncated at lens limit.
ORL-2007	QueryScopeDenied	error	403	Scope not permitted or missing.
ORL-2008	QueryTraceNotFound	error	404	Trace not found in retention.
ORL-2010	QueryUnknownVariable	error	400	OQL references a dashboard variable that was not provided.

Control

Code	Name	Severity	HTTP	Meaning
ORL-3001	ControlDuplicateSlug	error	409	Duplicate slug.
ORL-3002	ControlLastOwner	error	409	Cannot remove last owner.
ORL-3003	ControlInvalidRetention	error	422	Invalid retention or rollup configuration.
ORL-3004	ControlOIDCRejected	error	422	OIDC configuration rejected.
ORL-3005	ControlQuotaExceeded	error	422	Project or environment quota exceeded.
ORL-3006	ControlPermissionDenied	error	403	Permission denied, including escalation attempts.
ORL-3007	ControlBuiltinRoleImmutable	error	409	Built-in role is immutable.
ORL-3008	ControlRoleAssigned	error	409	Role deletion blocked because members still hold it.
ORL-3009	ControlAuthRequired	error	401	Authentication required or invalid credentials.
ORL-3010	ControlInviteInvalid	error	404	Invitation invalid, unknown, or revoked.
ORL-3011	ControlInviteExpired	error	410	Invitation expired.
ORL-3012	ControlInviteAccepted	error	409	Invitation already accepted.
ORL-3013	ControlEmailTaken	error	409	Email already registered.
ORL-3014	ControlSignupDisabled	error	403	Self-service signup disabled or invite-only instance.
ORL-3015	ControlDomainNotAllowed	error	403	Email domain is not in the allowlist.
ORL-3016	ControlWorkspaceCreationForbidden	error	403	Workspace creation is not permitted by policy.
ORL-3017	ControlRateLimited	error	429	Request rate limit exceeded.
ORL-3018	ControlInvitePending	error	409	A pending invitation already exists for this email.
ORL-3019	ControlDashboardVersionNotFound	error	404	Requested dashboard version does not exist.
ORL-3020	ControlAnnotationBadRange	error	400	Annotation end time precedes start time.

Alerting

Code	Name	Severity	HTTP	Meaning
ORL-4001	AlertDeliveryFailed	error	502	Channel delivery failed after retries.
ORL-4002	AlertEvalFailed	error	500	Rule evaluation failed.
ORL-4003	AlertInstanceOverflow	error	422	Rule produced a non-conforming shape or too many instances.

Storage

Code	Name	Severity	HTTP	Meaning
ORL-5001	StorageClickHouseUnavailable	error	503	ClickHouse unavailable.
ORL-5002	StorageSchemaMismatch	error	503	Schema version mismatch; migration required.
ORL-5003	StorageMetadataUnavailable	error	503	Metadata DB unavailable.
ORL-5004	StorageInternal	error	500	Unexpected internal error.
ORL-5005	StorageValkeyUnavailable	error	503	Valkey unavailable.

Feature flags

Code	Name	Severity	HTTP	Meaning
ORL-6001	FlagKeyConflict	error	409	Feature flag or segment key already exists in the project.
ORL-6002	FlagNotFound	error	404	Feature flag not found.
ORL-6003	FlagInvalid	error	422	Invalid flag, segment, targeting, or SDK key request.
ORL-6004	FlagsTokenInvalid	error	401	Missing or invalid feature-flag SDK token.
ORL-6005	FlagPrerequisiteCycle	error	422	Prerequisite change would create a cycle.
ORL-6006	FlagInUse	error	409	Flag is a prerequisite of another flag and cannot be deleted.
ORL-6007	FlagsServerTokenRequired	error	403	Endpoint requires a server-side feature-flag SDK token.
ORL-6008	FlagMetricKeyConflict	error	409	Metric key already exists.
ORL-6009	FlagMetricNotFound	error	404	Metric not found.
ORL-6010	FlagMetricInvalid	error	422	Metric definition invalid.
ORL-6011	FlagGuardedReleaseNotFound	error	404	Guarded release not found.
ORL-6012	FlagGuardedReleaseInvalid	error	422	Guarded release definition invalid.
ORL-6013	FlagGuardrailBreach	warn		Guarded release rolled back on a guardrail breach.
ORL-6014	FlagChangeNotFound	error	404	Deferred flag change not found.
ORL-6015	FlagChangeInvalid	error	422	Deferred flag change definition invalid.
ORL-6016	FlagChangeConflict	error	409	Deferred flag change cannot make this transition.

SLOs

Code	Name	Severity	HTTP	Meaning
ORL-7001	SLOInvalidDefinition	error	400	SLO definition is invalid.
ORL-7002	SLOEvalFailed	error	500	SLO evaluation failed.

Experiments

Code	Name	Severity	HTTP	Meaning
ORL-8001	ExperimentKeyConflict	error	409	Experiment key already exists in the project.
ORL-8002	ExperimentNotFound	error	404	Experiment not found.
ORL-8003	ExperimentInvalid	error	422	Invalid experiment or goal-metric definition.
ORL-8004	ExperimentStateConflict	error	409	Lifecycle transition not allowed.
ORL-8005	ExperimentLayerFull	error	409	Experiment layer has no room for the allocation.

Recording rules

Code	Name	Severity	HTTP	Meaning
ORL-9001	RecordingRuleInvalidDefinition	error	400	Recording rule definition is invalid.