Error reference

Osyra uses stable OSY-* codes for machine decisions. Human-readable messages can become clearer over time, so branch on the code and HTTP status rather than matching message text.

Response shapes

The response shape depends on the layer that rejects the request. Clients must preserve the stable OSY-* code across these envelopes instead of assuming that one JSON shape represents an entire URL family.

Cross-cutting Edge middleware—authentication, authorization, rate, quota, residency, and dependency gates—returns a flat Osyra envelope. This can occur before a native or /v1 route handler runs:

{
  "success": false,
  "error": "rate limit exceeded",
  "code": "OSY-RATE-2001",
  "request_id": "request-correlation-id",
  "timestamp": "2026-07-15T18:00:00Z"
}

After a native REST handler receives the request, its own validation and service errors use the native nested envelope:

{
  "error": {
    "code": "OSY-VALID-4001",
    "message": "invalid request"
  },
  "meta": {
    "request_id": "request-correlation-id"
  }
}

After a /v1 compatibility handler receives the request, its errors keep the envelope expected by OpenAI clients while carrying the Osyra code in error.code:

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error",
    "code": "OSY-RATE-2001"
  }
}

GraphQL uses the standard errors[] response and places the stable code in extensions.code. A GraphQL transport response can therefore be HTTP 200 while the operation itself was denied; inspect errors, not only the HTTP status.

In practical terms, a /v1 request rejected by authentication middleware can carry the flat envelope, while a validly authenticated request rejected by the OpenAI handler carries the OpenAI envelope. Parse defensively: first check whether error is a string or object, then read code from the corresponding location.

Edge returns X-Request-ID as the correlation identifier. Share that identifier with support; it lets operators correlate telemetry that the workspace's retention and no_store policy permits. It is not a promise that request or response bodies were retained.

When a response includes Retry-After, treat its value as seconds and honor it. Rate-limit and selected transient-availability responses carry this header; validation and authorization failures do not become retryable merely because a client can resend them.

Code families

| Prefix | Category | | ---------------- | ------------------------------------------- | | OSY-AUTH-* | Authentication and authorization | | OSY-RATE-* | Rate limiting and quota | | OSY-POLICY-* | Policy, residency, and governance decisions | | OSY-VALID-* | Request validation | | OSY-RESOURCE-* | Resource lookup | | OSY-CONFLICT-* | State conflict | | OSY-SERVER-* | Gateway or dependency availability |

Services can define additional domain-specific families. The code returned by the live operation is authoritative; the tables below are selected, audited examples from the shared Edge contract, not a complete registry.

Authentication and authorization

| Code | Typical HTTP | Meaning | Recovery | | --------------- | ------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | OSY-AUTH-1001 | 401 | Missing or invalid access token | Send one OAuth access token, or use the documented API-key transport | | OSY-AUTH-1002 | 401 | Access token expired | Obtain a new access token from auth.osyra.ai | | OSY-AUTH-1004 | 401 | API key rejected; unknown, expired, and revoked stay opaque | Stop using that credential and rotate it through an authorized console session | | OSY-AUTH-1005 | 401 | Access token or session revoked | Re-authenticate; do not retry the revoked token | | OSY-AUTH-1010 | 403 | Verified principal lacks the operation permission | Grant the least-privilege permission or use an appropriately authorized principal | | OSY-AUTH-1020 | 403 | Organization is outside the verified tenant boundary | Use a session issued for the target organization | | OSY-AUTH-1021 | 403 | Workspace is outside the verified tenant boundary | Use a session or key issued for the target workspace | | OSY-AUTH-1030 | 401 | Access-token audience does not identify the Osyra API | Request a token for the canonical API audience; do not use an authorization-server ID token | | OSY-AUTH-1032 | 401 | Token type is not valid for this operation | Present an OAuth access token or an API-key session, as the operation requires | | OSY-AUTH-1041 | 401/403 | A recent step-up authentication is required | Complete the prompted re-authentication and retry with the short-lived step-up token | | OSY-AUTH-1042 | 401/403 | Step-up proof is invalid, expired, replayed, or operation-mismatched | Repeat step-up for the exact operation |

Send exactly one credential channel. Native clients use X-Api-Key: osy_<class>_<secret> for API keys or Authorization: Bearer <OAuth access token>. OpenAI SDKs place their configured api_key in the Bearer header, so the /v1 compatibility path also accepts Authorization: Bearer osy_* only when it has an exact key shape minted by IAM. Do not send both headers.

Rate and quota

| Code | Typical HTTP | Meaning | Recovery | | --------------- | ------------ | ----------------------------------------- | ------------------------------------------------------------------------------------- | | OSY-RATE-2001 | 429 | Request or API-key rate limit reached | Honor Retry-After, add jitter, and reduce concurrency | | OSY-RATE-2010 | 429 | Current subscription-period quota reached | Inspect quota details and the period reset; change policy or plan through an operator |

Quota periods are subscription-relative. Never calculate a reset from the first day of a calendar month; use the reset information returned by the service.

Policy

| Code | Typical HTTP | Meaning | Recovery | | ----------------- | ------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------- | | OSY-POLICY-3001 | 403 | A verified policy denied the operation | Review the attached policy and the operation's permissions | | OSY-POLICY-3060 | 421 | Request reached a region other than the workspace home | Follow the validated region redirect and resend there | | OSY-POLICY-3061 | 403 | Workspace home region could not be resolved safely | Stop and resolve the workspace region configuration; Osyra does not guess a region | | OSY-POLICY-3400 | 403 | Virtual key is revoked | Stop using the alias and issue a replacement |

Policy denials fail closed. Do not automatically retry a 403 against another provider; that would turn routing into a policy bypass.

Validation and resource state

| Code | Typical HTTP | Meaning | Recovery | | ------------------- | ------------ | ----------------------------------------- | ------------------------------------------------- | | OSY-VALID-4001 | 400 | Request body or operation is invalid | Validate the request against the documented shape | | OSY-VALID-4002 | 400 | Parameter format or range is invalid | Correct the named parameter | | OSY-VALID-4003 | 400 | Required field is missing | Add the field named by the response | | OSY-VALID-4005 | 405 | HTTP method is not allowed for this path | Use the method in the endpoint contract | | OSY-RESOURCE-6001 | 404 | Authorized lookup found no resource | Verify the opaque identifier in the same tenant | | OSY-CONFLICT-7001 | 409 | Requested state conflicts with live state | Re-read the resource and retry only if safe |

Availability

| Code | Typical HTTP | Meaning | Recovery | | ----------------- | ------------ | -------------------------------------------------------- | ------------------------------------------------------------ | | OSY-SERVER-9001 | 500 | Internal failure without a safe client-facing detail | Report X-Request-ID; retry only when the operation is safe | | OSY-SERVER-9002 | 503 | Required service or authorization dependency unavailable | Honor Retry-After when present and use exponential backoff | | OSY-SERVER-9007 | 503 | Edge circuit breaker is open | Honor Retry-After; do not create a retry storm | | OSY-SERVER-9050 | 501 | Route exists but the capability is not implemented | Do not retry; use a documented available capability |

Client decision order

1. Parse the response shape for the surface you called.
2. Record X-Request-ID, HTTP status, and the stable OSY-* code without logging credentials or prompt content.
3. Refresh credentials only for the matching authentication condition.
4. Retry only safe operations and only retryable statuses, honoring Retry-After with jitter.
5. Surface validation, policy, and permission failures to the operator who can change the request or configuration.

What's next

• Authentication — credential transports and tenant boundaries
• Making requests — the native and OpenAI-compatible surfaces
• Governance & policy — policy decisions and audit evidence