Error Code Catalog

Every OSYRA error carries a stable, machine-readable code in the form OSY-<CATEGORY>-<NNNN>. The code identifies the error class independent of the human-readable message (which may be localized), so clients can branch on it programmatically.

OSY-AUTH-1002
└┬┘ └─┬┘ └─┬┘
 │    │    └─ NNNN  numeric code (band-allocated per category)
 │    └────── CATEGORY  domain prefix (AUTH, RATE, POLICY, …)
 └─────────── OSY  fixed OSYRA namespace

The canonical registry of cross-service codes is osyra-response-common (ErrorCodes.java). Individual services additionally allocate codes within service-owned numeric bands (for example the memory service OSY-MEM-5xxx, the verifier OSY-VIR-56xx, and continuous-attestation OSY-DRIFT-62xx). The canonical category table applies to the prefixes represented by ErrorCategory; the separate service-owned table records namespace ownership only. Service-owned numeric bands can overlap canonical category numbers and do not, by themselves, determine an HTTP or gRPC status.

Stability. New allocations are append-only and must not reuse an existing value. Two pre-existing validation-code collisions remain recorded pending registry cleanup: OSY-VALID-4020 means either INVALID_TEMPERATURE or SUBJECT_NOT_PROOFED, and OSY-VALID-4021 means either INVALID_MAX_TOKENS or SUBJECT_SENTINEL_FORBIDDEN. Until those collisions are remediated, interpret those two values in the context of the API operation that emitted them. Deprecated codes (for example the pre-V2 TENANT_* variants) remain valid for backward compatibility and are marked Deprecated in the tables below.

Category taxonomy

The canonical taxonomy and its default HTTP / gRPC mapping is defined by the ErrorCategory enum in osyra-response-common.

| Category prefix | Band | Meaning | Default HTTP | gRPC | |---|---|---|---|---| | OSY-AUTH- | 1000–1999 | Authentication — no identity, or identity invalid (expired/missing/revoked token, signature failure) | 401 | UNAUTHENTICATED | | OSY-RATE- | 2000–2999 | Rate limiting and quotas | 429 | RESOURCE_EXHAUSTED | | OSY-POLICY- | 3000–3999 | Policy violations (SCP deny, budget, content moderation, WAF, model/time/geo restrictions) | 403 | FAILED_PRECONDITION | | OSY-VALID- | 4000–4999 | Validation errors (malformed input, schema, LLM-parameter validation, business rules) | 400 | INVALID_ARGUMENT | | OSY-PROV- | 5000–5099 | Provider / external-service errors (Model-Broker adapter edge) | 502 | UNAVAILABLE | | OSY-MEM- | 5100–5599 | Memory service errors (AP00011 Osymem, per ADR-031) | 422 (per-code overrides) | — | | OSY-RESOURCE- | 6000–6999 | Resource not found | 404 | NOT_FOUND | | OSY-CONFLICT- | 7000–7999 | Conflict errors (duplicate resource, concurrent modification, state) | 409 | ALREADY_EXISTS / ABORTED | | OSY-INFER- | 8100–8199 | Inference-execution errors (AP00008 model-execution path) | 502 | UNAVAILABLE | | OSY-SERVER- | 9000–9999 | Internal server errors (database, cache, configuration, not-implemented) | 500 / 503 | INTERNAL / UNAVAILABLE |

Two additional logical categories share existing numeric bands rather than a distinct prefix:

• PERMISSION_DENIED — identity present but lacks permission for the action (distinct from AUTH = no identity, and from POLICY = an OPA rule denied). Maps to HTTP 403 / gRPC PERMISSION_DENIED.
• Business rules are emitted under the OSY-VALID- prefix (see BUSINESS_RULE_VIOLATION = OSY-VALID-4050).

BILL is a domain prefix, not an ErrorCategory. Its factories use the canonical VALIDATION, AUTH, or SERVER categories and set an explicit per-code HTTP status. In particular, the 93xx number does not make every OSY-BILL-* response an internal-server error.

Service-owned bands

Beyond the cross-service registry, services allocate codes inside their own domain prefixes. This is a deliberately narrow, source-confirmed ownership index, not an exhaustive transport-status table. Consult the originating service for each member's meaning and actual HTTP/gRPC mapping.

| Prefix(es) | Owner / current scope | |---|---| | OSY-VIR-56xx | AP00016 Verifier-of-Record | | OSY-BROKER-5600 | AP00001 Edge broker NOT-WIRED surface; the current source emits the literal OSY-BROKER-NOT-WIRED and reserves numeric 5600+ for later broker failure detail | | OSY-DRIFT-62xx, OSY-ATTLOG-78xx | AP00012 continuous-attestation and attested-log service | | OSY-EAT-63xx, OSY-OAHR-81xx | AP00016; OAHR is currently reserved-not-minted | | OSY-INFER-81xx | AP00008 inference service | | OSY-WF-80xx | AP00007 workflow service | | OSY-ADMIN-82xx | AP00009 admin gateway | | OSY-AMGATE-85xx | AP00011 OME attested-memory gate |

OSY-AUTH — Authentication (1000–1999)

Sub-bands: 1000–1029 general · 1030–1039 token · 1040–1049 session · 1050–1069 user · 1070–1089 password · 1100–1119 KMS / cryptographic.

| Code | Meaning | Defined | |---|---|---| | OSY-AUTH-1001 | Authentication failed — invalid credentials or token | ErrorCodes.AUTH_FAILED | | OSY-AUTH-1002 | Authentication token has expired | ErrorCodes.TOKEN_EXPIRED | | OSY-AUTH-1003 | Multi-factor authentication is required | ErrorCodes.MFA_REQUIRED | | OSY-AUTH-1004 | Invalid credentials provided | ErrorCodes.INVALID_CREDENTIALS | | OSY-AUTH-1005 | Authentication token has been revoked | ErrorCodes.TOKEN_REVOKED | | OSY-AUTH-1010 | Insufficient permissions to access the resource | ErrorCodes.INSUFFICIENT_PERMISSIONS | | OSY-AUTH-1011 | Role not found or invalid | ErrorCodes.ROLE_NOT_FOUND | | OSY-AUTH-1020 | Tenant access denied (Deprecated — use OSY-AUTH-1021) | ErrorCodes.TENANT_ACCESS_DENIED | | OSY-AUTH-1021 | Workspace access denied (V2 architecture) | ErrorCodes.WORKSPACE_ACCESS_DENIED | | OSY-AUTH-1030 | Token audience mismatch | ErrorCodes.TOKEN_AUDIENCE_MISMATCH | | OSY-AUTH-1031 | Token replay detected (jti already used) | ErrorCodes.TOKEN_JTI_REPLAY | | OSY-AUTH-1032 | Insufficient token scope | ErrorCodes.TOKEN_INSUFFICIENT_SCOPE | | OSY-AUTH-1033 | Invalid client credentials | ErrorCodes.INVALID_CLIENT | | OSY-AUTH-1034 | Invalid or expired refresh token | ErrorCodes.REFRESH_TOKEN_INVALID | | OSY-AUTH-1040 | Associated session not found | ErrorCodes.SESSION_NOT_FOUND | | OSY-AUTH-1041 | Step-up re-authentication required for a sensitive operation | ErrorCodes.STEP_UP_REQUIRED | | OSY-AUTH-1042 | Step-up verification failed | ErrorCodes.STEP_UP_FAILED | | OSY-AUTH-1050 | User not found by username | ErrorCodes.USER_NOT_FOUND_BY_USERNAME | | OSY-AUTH-1051 | User not found by email | ErrorCodes.USER_NOT_FOUND_BY_EMAIL | | OSY-AUTH-1052 | User not found in tenant (Deprecated — use OSY-AUTH-1053) | ErrorCodes.USER_NOT_FOUND_IN_TENANT | | OSY-AUTH-1053 | User not found in workspace (V2 architecture) | ErrorCodes.USER_NOT_FOUND_IN_WORKSPACE | | OSY-AUTH-1070 | Invalid password provided | ErrorCodes.INVALID_PASSWORD | | OSY-AUTH-1071 | Password has expired | ErrorCodes.PASSWORD_EXPIRED | | OSY-AUTH-1072 | Password does not meet security requirements | ErrorCodes.WEAK_PASSWORD | | OSY-AUTH-1073 | Password has been used recently | ErrorCodes.PASSWORD_REUSED | | OSY-AUTH-1074 | Account locked due to failed login attempts | ErrorCodes.ACCOUNT_LOCKED | | OSY-AUTH-1075 | Temporary password is invalid or expired | ErrorCodes.TEMPORARY_PASSWORD_INVALID | | OSY-AUTH-1100 | KMS provider unavailable | ErrorCodes.KMS_PROVIDER_UNAVAILABLE | | OSY-AUTH-1101 | KMS signing operation failed | ErrorCodes.KMS_SIGN_FAILED | | OSY-AUTH-1102 | KMS key not found | ErrorCodes.KMS_KEY_NOT_FOUND | | OSY-AUTH-1103 | JWKS rotation in progress | ErrorCodes.JWKS_ROTATION_IN_PROGRESS | | OSY-AUTH-1104 | Algorithm not permitted | ErrorCodes.ALG_NOT_PERMITTED | | OSY-AUTH-1105 | Cryptographic signature failed | ErrorCodes.CRYPTO_SIGNATURE_FAILED | | OSY-AUTH-1106 | Cryptographic verification failed | ErrorCodes.CRYPTO_VERIFICATION_FAILED |

OSY-RATE — Rate limiting & quotas (2000–2999)

Sub-bands: 2000–2009 rate limits · 2010–2019 quotas.

| Code | Meaning | Defined | |---|---|---| | OSY-RATE-2001 | Rate limit exceeded (generic) | ErrorCodes.RATE_LIMIT_EXCEEDED | | OSY-RATE-2002 | Per-user rate limit exceeded | ErrorCodes.RATE_LIMIT_USER | | OSY-RATE-2003 | Per-tenant rate limit exceeded (Deprecated — use OSY-RATE-2009) | ErrorCodes.RATE_LIMIT_TENANT | | OSY-RATE-2004 | Per-organization rate limit exceeded | ErrorCodes.RATE_LIMIT_ORG | | OSY-RATE-2005 | Per-IP rate limit exceeded | ErrorCodes.RATE_LIMIT_IP | | OSY-RATE-2006 | Per-project rate limit exceeded | ErrorCodes.RATE_LIMIT_PROJECT | | OSY-RATE-2007 | Global rate limit exceeded | ErrorCodes.RATE_LIMIT_GLOBAL | | OSY-RATE-2008 | Burst rate limit exceeded | ErrorCodes.RATE_LIMIT_BURST | | OSY-RATE-2009 | Per-workspace rate limit exceeded (V2 architecture) | ErrorCodes.RATE_LIMIT_WORKSPACE | | OSY-RATE-2010 | Quota exceeded (generic) | ErrorCodes.QUOTA_EXCEEDED | | OSY-RATE-2011 | Token quota exceeded | ErrorCodes.QUOTA_TOKEN_EXCEEDED | | OSY-RATE-2012 | Request quota exceeded | ErrorCodes.QUOTA_REQUEST_EXCEEDED | | OSY-RATE-2013 | User quota exceeded (plan limit on number of users) | ErrorCodes.QUOTA_USER_EXCEEDED | | OSY-RATE-2014 | Workspace quota exceeded (plan limit on number of workspaces) | ErrorCodes.QUOTA_WORKSPACE_EXCEEDED | | OSY-RATE-2015 | Metered-spend budget exceeded under hard enforcement | ErrorCodes.BUDGET_SPEND_EXCEEDED |

OSY-POLICY — Policy violations (3000–3999)

Sub-bands: 3000–3019 general · 3020–3029 content moderation · 3030–3049 WAF / security · 3050–3059 model / time / geo restrictions.

| Code | Meaning | Defined | |---|---|---| | OSY-POLICY-3001 | Policy violation (generic) | ErrorCodes.POLICY_VIOLATION | | OSY-POLICY-3002 | Service Control Policy (SCP) deny | ErrorCodes.SCP_DENY | | OSY-POLICY-3010 | Budget limit exceeded (generic) | ErrorCodes.BUDGET_EXCEEDED | | OSY-POLICY-3011 | Daily budget limit exceeded | ErrorCodes.BUDGET_DAILY_EXCEEDED | | OSY-POLICY-3012 | Monthly budget limit exceeded | ErrorCodes.BUDGET_MONTHLY_EXCEEDED | | OSY-POLICY-3020 | Content moderation violation (generic) | ErrorCodes.CONTENT_VIOLATION | | OSY-POLICY-3021 | Personally Identifiable Information (PII) detected | ErrorCodes.PII_DETECTED | | OSY-POLICY-3022 | Prompt injection attack detected | ErrorCodes.PROMPT_INJECTION_DETECTED | | OSY-POLICY-3030 | SQL injection attempt detected | ErrorCodes.WAF_SQL_INJECTION | | OSY-POLICY-3031 | Path traversal attempt detected | ErrorCodes.WAF_PATH_TRAVERSAL | | OSY-POLICY-3032 | Cross-site scripting (XSS) attempt detected | ErrorCodes.WAF_XSS_DETECTED | | OSY-POLICY-3033 | Suspicious user agent detected | ErrorCodes.WAF_BAD_USER_AGENT | | OSY-POLICY-3034 | Anomalous request pattern detected | ErrorCodes.WAF_ANOMALY_DETECTED | | OSY-POLICY-3035 | IP address temporarily blocked | ErrorCodes.WAF_IP_BLOCKED | | OSY-POLICY-3036 | Request payload too large | ErrorCodes.WAF_REQUEST_TOO_LARGE | | OSY-POLICY-3050 | Model not allowed by policy | ErrorCodes.POLICY_MODEL_NOT_ALLOWED | | OSY-POLICY-3051 | Request outside allowed time window | ErrorCodes.POLICY_TIME_RESTRICTED | | OSY-POLICY-3052 | Request from restricted geographic location | ErrorCodes.POLICY_GEO_RESTRICTED |

The policy-compute engine (AP00019) additionally emits codes in the OSY-PCE-64xx band, and downstream policy receipt/registry families use OSY-POLREG-* / OSY-POLSPEC-*. Those are owned and documented by their originating service.

OSY-VALID — Validation (4000–4999)

Sub-bands: 4000–4019 general · 4020–4039 LLM-specific · 4040–4049 FinOps / billing validation. Business-rule violations are also emitted under this prefix.

| Code | Meaning | Defined | |---|---|---| | OSY-VALID-4001 | Validation failed (generic) | ErrorCodes.VALIDATION_FAILED | | OSY-VALID-4002 | Invalid parameter provided | ErrorCodes.INVALID_PARAMETER | | OSY-VALID-4003 | Required parameter is missing | ErrorCodes.MISSING_PARAMETER | | OSY-VALID-4010 | Invalid email format | ErrorCodes.INVALID_EMAIL | | OSY-VALID-4011 | Invalid model specified | ErrorCodes.INVALID_MODEL | | OSY-VALID-4012 | Invalid JSON format | ErrorCodes.INVALID_JSON | | OSY-VALID-4013 | Schema mismatch | ErrorCodes.SCHEMA_MISMATCH | | OSY-VALID-4016 | Signed provider-spec registry bundle verification failed | ErrorCodes.SIGNED_BUNDLE_VERIFY_FAILED | | OSY-VALID-4017 | Provider-spec base URL rejected by the SSRF / host-allowlist guard | ErrorCodes.SSRF_REJECTED | | OSY-VALID-4020 | Invalid temperature parameter; legacy collision with DSAR SUBJECT_NOT_PROOFED | ErrorCodes.INVALID_TEMPERATURE | | OSY-VALID-4021 | Invalid max_tokens parameter; legacy collision with DSAR SUBJECT_SENTINEL_FORBIDDEN | ErrorCodes.INVALID_MAX_TOKENS | | OSY-VALID-4022 | Token limit exceeded for model | ErrorCodes.TOKEN_LIMIT_EXCEEDED | | OSY-VALID-4023 | Prompt is too long | ErrorCodes.PROMPT_TOO_LONG | | OSY-VALID-4024 | System prompt is invalid | ErrorCodes.SYSTEM_PROMPT_INVALID | | OSY-VALID-4041 | Workspace default provider is not eligible for the requested model | ErrorCodes.DEFAULT_PROVIDER_INELIGIBLE | | OSY-VALID-4042 | No eligible provider exists for the requested default model | ErrorCodes.DEFAULT_PROVIDER_UNKNOWN_MODEL | | OSY-VALID-4050 | Business rule violation | ErrorCodes.BUSINESS_RULE_VIOLATION |

OSY-PROV — Provider / external service (5000–5099)

Sub-bands: 5000–5019 provider-specific · 5020–5039 extended provider errors.

| Code | Meaning | Defined | |---|---|---| | OSY-PROV-5001 | External provider is unavailable | ErrorCodes.PROVIDER_UNAVAILABLE | | OSY-PROV-5002 | Provider returned an error | ErrorCodes.PROVIDER_ERROR | | OSY-PROV-5003 | Provider request timed out | ErrorCodes.PROVIDER_TIMEOUT | | OSY-PROV-5010 | OpenAI provider error | ErrorCodes.OPENAI_ERROR | | OSY-PROV-5011 | Anthropic provider error | ErrorCodes.ANTHROPIC_ERROR | | OSY-PROV-5012 | Azure provider error | ErrorCodes.AZURE_ERROR | | OSY-PROV-5020 | Provider circuit breaker is open | ErrorCodes.PROVIDER_CIRCUIT_OPEN | | OSY-PROV-5021 | Provider configuration error | ErrorCodes.PROVIDER_CONFIGURATION_ERROR | | OSY-PROV-5022 | Provider connection timeout | ErrorCodes.PROVIDER_CONNECTION_TIMEOUT | | OSY-PROV-5023 | Invalid token from provider | ErrorCodes.PROVIDER_INVALID_TOKEN | | OSY-PROV-5024 | Rate limited by provider | ErrorCodes.PROVIDER_RATE_LIMITED | | OSY-PROV-5025 | User not found at provider | ErrorCodes.PROVIDER_USER_NOT_FOUND | | OSY-PROV-5026 | Failed to parse provider response | ErrorCodes.PROVIDER_RESPONSE_PARSING_ERROR | | OSY-PROV-5027 | SSL/TLS certificate error with provider | ErrorCodes.PROVIDER_CERTIFICATE_ERROR | | OSY-PROV-5028 | Provider authentication failed | ErrorCodes.PROVIDER_AUTHENTICATION_FAILED | | OSY-PROV-5029 | Invalid model for provider | ErrorCodes.PROVIDER_INVALID_MODEL | | OSY-PROV-5030 | Provider quota exceeded | ErrorCodes.PROVIDER_QUOTA_EXCEEDED |

OSY-MEM — Memory service (5100–5599)

Allocated to the AP00011 Osymem service per ADR-031. Sub-bands: 5100–5149 claim signing/verification · 5150–5199 JMT · 5200–5249 witness · 5250–5299 bundle · 5300–5349 WBW/GUC/multi-tenancy (P0 security) · 5350–5399 era-secret/BYOK/KMS · 5400–5449 DID resolution/trust anchors · 5450–5499 ClaimKind registry · 5500–5549 migration.

The codes below are the registered members in the cross-service registry (ErrorCodes.java). The Osymem service maintains an additional, larger local catalog (OsymemErrorCodes) within the same OSY-MEM-5xxx band; consult the AP00011 service reference for codes not listed here.

| Code | Meaning | Defined | |---|---|---| | OSY-MEM-5101 | Claim signature is invalid (Ed25519 verify failed) | ErrorCodes.MEM_INVALID_SIGNATURE | | OSY-MEM-5102 | Malformed canonical CBOR (RFC 8949 §4.2.1 violation) | ErrorCodes.MEM_MALFORMED_CBOR | | OSY-MEM-5103 | Claim domain-separation tag mismatch (cross-protocol confusion attempt) | ErrorCodes.MEM_DOMAIN_TAG_MISMATCH | | OSY-MEM-5104 | Claim content hash does not match supplied body (sha256 mismatch) | ErrorCodes.MEM_CONTENT_HASH_MISMATCH | | OSY-MEM-5105 | Invalid or unrecognised ClaimKind | ErrorCodes.MEM_INVALID_CLAIM_KIND | | OSY-MEM-5106 | Missing a required preimage field (id, workspace_id, issuer_did, …) | ErrorCodes.MEM_MISSING_PREIMAGE_FIELD | | OSY-MEM-5151 | JMT inclusion / non-membership proof verification failed | ErrorCodes.MEM_JMT_PROOF_INVALID | | OSY-MEM-5152 | JMT root mismatch (computed root differs from expected) | ErrorCodes.MEM_JMT_ROOT_MISMATCH | | OSY-MEM-5153 | JMT key length invalid (must be 32-byte SHA-256 digest) | ErrorCodes.MEM_JMT_KEY_LENGTH_INVALID | | OSY-MEM-5201 | Completeness witness signature invalid | ErrorCodes.MEM_WITNESS_SIGNATURE_INVALID | | OSY-MEM-5202 | Witness gap-proof reconstruction failed | ErrorCodes.MEM_WITNESS_GAP_PROOF_INVALID | | OSY-MEM-5203 | Witness epoch outside accepted [minEpoch, maxEpoch] window (replay protection) | ErrorCodes.MEM_WITNESS_EPOCH_OUT_OF_WINDOW | | OSY-MEM-5204 | Witness boundaries not in strictly ascending order | ErrorCodes.MEM_WITNESS_BOUNDARIES_NOT_ASCENDING | | OSY-MEM-5251 | Bundle manifest CBOR parse error | ErrorCodes.MEM_BUNDLE_MANIFEST_PARSE_ERROR | | OSY-MEM-5252 | Bundle root reconstruction does not match Manifest.RootHex | ErrorCodes.MEM_BUNDLE_ROOT_MISMATCH | | OSY-MEM-5253 | Bundle Bundler signature (COSE_Sign1) invalid | ErrorCodes.MEM_BUNDLE_BUNDLER_SIG_INVALID | | OSY-MEM-5254 | Bundle import refuses to overwrite non-empty target workspace | ErrorCodes.MEM_BUNDLE_TARGET_NOT_EMPTY | | OSY-MEM-5301 | Workspace not found in placement registry | ErrorCodes.MEM_WORKSPACE_NOT_FOUND | | OSY-MEM-5302 | Cross-organization workspace operation forbidden in V1 | ErrorCodes.MEM_CROSS_ORG_FORBIDDEN_V1 | | OSY-MEM-5303 | Residency violation (cross-region operation forbidden by ADR-026 cell topology) | ErrorCodes.MEM_RESIDENCY_VIOLATION | | OSY-MEM-5310 | WBW GUC path mismatch (issuer signing for wrong workspace) — P0 security | ErrorCodes.MEM_WBW_GUC_PATH_MISMATCH | | OSY-MEM-5311 | WBW GUC (osymem.workspace_id) missing — P0 security | ErrorCodes.MEM_WBW_GUC_MISSING | | OSY-MEM-5312 | Cross-tenant ∧ conjunction rejected by I-TENANT-1 invariant | ErrorCodes.MEM_CROSS_TENANT_CONJUNCTION | | OSY-MEM-5351 | AWS KMS Decrypt operation failed (transient; retryable) | ErrorCodes.MEM_KMS_DECRYPT_FAILED | | OSY-MEM-5352 | KMS grant revoked by customer (GDPR Art. 17 cryptographic erasure complete) | ErrorCodes.MEM_KMS_GRANT_REVOKED | | OSY-MEM-5353 | era_secret unrecoverable (cache miss + KMS failure or grant revoked) | ErrorCodes.MEM_ERA_SECRET_UNRECOVERABLE | | OSY-MEM-5401 | DID resolution via IAM service failed (transient; retryable) | ErrorCodes.MEM_DID_RESOLUTION_FAILED | | OSY-MEM-5402 | DID method not supported (V1: did:web, did:key only; non-retryable) | ErrorCodes.MEM_DID_METHOD_UNSUPPORTED | | OSY-MEM-5403 | Issuer DID not in pinned trust-anchor registry (non-retryable; high-severity audit) | ErrorCodes.MEM_ISSUER_NOT_TRUSTED | | OSY-MEM-5451 | Unknown claim kind (strict-mode rejection; non-retryable) | ErrorCodes.MEM_UNKNOWN_CLAIM_KIND | | OSY-MEM-5452 | Claim-kind version downgrade attempt rejected | ErrorCodes.MEM_KIND_VERSION_DOWNGRADE | | OSY-MEM-5501 | Tier migration in progress (5-min read-only window; retryable with backoff) | ErrorCodes.MEM_TIER_MIGRATION_IN_PROGRESS | | OSY-MEM-5502 | Era rotation in progress (≤1h cache TTL; retryable with backoff) | ErrorCodes.MEM_ERA_ROTATION_IN_PROGRESS |

OSY-RESOURCE — Resource not found (6000–6999)

Sub-bands: 6000–6019 general · 6020–6029 organization · 6030–6039 client.

| Code | Meaning | Defined | |---|---|---| | OSY-RESOURCE-6001 | Resource not found (generic) | ErrorCodes.RESOURCE_NOT_FOUND | | OSY-RESOURCE-6010 | Tenant not found (Deprecated — use OSY-RESOURCE-6013) | ErrorCodes.TENANT_NOT_FOUND | | OSY-RESOURCE-6011 | User not found | ErrorCodes.USER_NOT_FOUND | | OSY-RESOURCE-6012 | Model not found | ErrorCodes.MODEL_NOT_FOUND | | OSY-RESOURCE-6013 | Workspace not found | ErrorCodes.WORKSPACE_NOT_FOUND | | OSY-RESOURCE-6020 | Organization not found | ErrorCodes.ORGANIZATION_NOT_FOUND | | OSY-RESOURCE-6021 | Organizational Unit (OU) not found | ErrorCodes.OU_NOT_FOUND | | OSY-RESOURCE-6030 | Client not found | ErrorCodes.CLIENT_NOT_FOUND | | OSY-RESOURCE-6031 | Client is disabled | ErrorCodes.CLIENT_DISABLED |

OSY-CONFLICT — Conflicts (7000–7999)

Sub-bands: 7000–7019 general · 7020–7029 organization · 7030–7039 client · 7040–7049 state.

| Code | Meaning | Defined | |---|---|---| | OSY-CONFLICT-7001 | Duplicate resource (generic) | ErrorCodes.DUPLICATE_RESOURCE | | OSY-CONFLICT-7002 | Concurrent modification detected | ErrorCodes.CONCURRENT_MODIFICATION | | OSY-CONFLICT-7010 | Duplicate email address | ErrorCodes.DUPLICATE_EMAIL | | OSY-CONFLICT-7011 | Duplicate tenant (Deprecated — use OSY-CONFLICT-7012) | ErrorCodes.DUPLICATE_TENANT | | OSY-CONFLICT-7012 | Duplicate workspace (V2 architecture) | ErrorCodes.DUPLICATE_WORKSPACE | | OSY-CONFLICT-7020 | Duplicate organization | ErrorCodes.DUPLICATE_ORGANIZATION | | OSY-CONFLICT-7021 | Invalid organization structure | ErrorCodes.INVALID_ORG_STRUCTURE | | OSY-CONFLICT-7022 | Invalid OU hierarchy | ErrorCodes.INVALID_OU_HIERARCHY | | OSY-CONFLICT-7030 | Duplicate client | ErrorCodes.DUPLICATE_CLIENT | | OSY-CONFLICT-7031 | Invalid client secret | ErrorCodes.INVALID_CLIENT_SECRET | | OSY-CONFLICT-7032 | Invalid client configuration | ErrorCodes.INVALID_CLIENT_CONFIG | | OSY-CONFLICT-7040 | Invalid state | ErrorCodes.STATE_INVALID | | OSY-CONFLICT-7041 | State has expired | ErrorCodes.STATE_EXPIRED | | OSY-CONFLICT-7042 | State already used | ErrorCodes.STATE_ALREADY_USED | | OSY-CONFLICT-7043 | State mismatch | ErrorCodes.STATE_MISMATCH |

OSY-INFER — Inference execution (8100–8199)

These codes describe the customer-private inference path. Security, capacity, and reachability failures are surfaced honestly; they never silently fall back to a shared provider pool.

| Code | Meaning | Defined | |---|---|---| | OSY-INFER-8124 | No active private endpoint is available for the workspace and model | ErrorCodes.INFER_NO_ACTIVE_PRIVATE_ENDPOINT | | OSY-INFER-8146 | The private endpoint's presented mTLS CA pin does not match its registration | ErrorCodes.INFER_CA_PIN_MISMATCH | | OSY-INFER-8161 | The private endpoint timed out | ErrorCodes.INFER_PRIVATE_ENDPOINT_TIMEOUT | | OSY-INFER-8164 | The private endpoint is saturated | ErrorCodes.INFER_ENDPOINT_SATURATED | | OSY-INFER-8165 | The private endpoint is unreachable | ErrorCodes.INFER_ENDPOINT_UNREACHABLE |

OSY-SERVER — Internal server errors (9000–9999)

Sub-bands: 9000–9019 general · 9020–9029 database · 9030–9039 cache · 9040–9049 configuration.

| Code | Meaning | Defined | |---|---|---| | OSY-SERVER-9001 | Internal server error (generic) | ErrorCodes.INTERNAL_ERROR | | OSY-SERVER-9002 | Service is unavailable | ErrorCodes.SERVICE_UNAVAILABLE | | OSY-SERVER-9007 | RPC attempted on a disposed/closed SDK client (client lifecycle) | ErrorCodes.CLIENT_CLOSED | | OSY-SERVER-9010 | Database error | ErrorCodes.DATABASE_ERROR | | OSY-SERVER-9011 | Cache error | ErrorCodes.CACHE_ERROR | | OSY-SERVER-9020 | Database connection failed | ErrorCodes.DATABASE_CONNECTION_FAILED | | OSY-SERVER-9021 | Database query failed | ErrorCodes.DATABASE_QUERY_FAILED | | OSY-SERVER-9022 | Database transaction failed | ErrorCodes.DATABASE_TRANSACTION_FAILED | | OSY-SERVER-9030 | Cache read failed | ErrorCodes.CACHE_READ_FAILED | | OSY-SERVER-9031 | Cache write failed | ErrorCodes.CACHE_WRITE_FAILED | | OSY-SERVER-9040 | Configuration load failed | ErrorCodes.CONFIG_LOAD_FAILED | | OSY-SERVER-9041 | Configuration has invalid format | ErrorCodes.CONFIG_INVALID_FORMAT | | OSY-SERVER-9050 | Feature not implemented | ErrorCodes.NOT_IMPLEMENTED |

OSY-BILL — Billing money-path (9370–9399)

Billing-specific wire codes are centralized in the cross-service registry so AP00003 and future money-path services do not own local string constants.

| Code | Meaning | ErrorCategory | HTTP | Defined | |---|---|---|---|---| | OSY-BILL-9372 | Storage reclamation failed a required precondition | VALIDATION | 412 | ErrorCodes.BILLING_RECLAMATION_FAILED_PRECONDITION | | OSY-BILL-9374 | Storage reclamation idempotency key / ticket binding invalid | VALIDATION | 400 | ErrorCodes.BILLING_RECLAMATION_INVALID_IDEMPOTENCY_KEY | | OSY-BILL-9375 | Storage reclamation approval JWS rejected or replayed | AUTH | 403 | ErrorCodes.BILLING_RECLAMATION_JWS_REJECTED | | OSY-BILL-9376 | Storage reclamation blocked by an active legal hold | VALIDATION | 412 | ErrorCodes.BILLING_RECLAMATION_LEGAL_HOLD | | OSY-BILL-9377 | Storage reclamation blocked — Stripe shows legitimate payment activity | VALIDATION | 412 | ErrorCodes.BILLING_RECLAMATION_STRIPE_LEGITIMATE | | OSY-BILL-9378 | Storage reclamation requires an operator-notification step before mutation | VALIDATION | 412 | ErrorCodes.BILLING_RECLAMATION_NOTIFICATION_REQUIRED | | OSY-BILL-9398 | Storage reclamation failed due to an internal service error | SERVER | 500 | ErrorCodes.BILLING_RECLAMATION_INTERNAL |

Notes for integrators

• Branch on the code, not the message. Messages are localized (the registry ships messages.properties and messages_ar.properties) and may change; codes are stable except for the two documented legacy validation collisions above, which also require API-operation context.
• Unknown codes are forward-compatible. New codes are added over time. Use the actual HTTP status or gRPC status returned with an unrecognized code. Do not infer transport behavior from the numeric band or domain prefix; this is especially important for service-owned prefixes and OSY-BILL-*.
• Deprecated codes still resolve. Pre-V2 *_TENANT codes (OSY-AUTH-1020, OSY-AUTH-1052, OSY-RATE-2003, OSY-RESOURCE-6010, OSY-CONFLICT-7011) remain valid; new integrations should prefer the workspace-scoped successors noted in the tables.

Source of truth: osyra-response-common/src/main/java/ai/osyra/response/ErrorCodes.java plus ErrorCategory.java and the per-code factories in OsyraException.java. Service-owned bands are governed by their originating service. Last verified 2026-07-23.