Diagnostics

Diagnostic codes are stable, structured errors and warnings. API errors include the code and human message; ingest partial-success responses 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-2009	QueryScopeIgnored	warn		Requested environment scope is not applicable to traces.

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-3018	ControlInvitePending	error	409	A pending invitation already exists for this email.

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.

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.