API errors

Every handled Operade API failure uses a stable JSON envelope. Use the HTTP status for the broad class and error.code for program decisions. Treat message and details as diagnostic context, not presentation copy.

Response shape#

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "fields": [
        {"field": "name", "message": "Name is required."}
      ]
    }
  }
}

details is optional. Validation failures that identify fields use a fields array. Other errors can carry operational identifiers, configuration names, a retry interval, or stale-state identifiers. Code should tolerate the absence of details and must not infer a hidden value from it.

Status classes#

HTTP 401 covers missing, expired, invalid, or revoked authentication. HTTP 403 covers a known caller without the required permission or credential type. HTTP 404 means absent or outside Workspace scope. HTTP 409 reports state conflicts such as stale drafts and previews. HTTP 422 reports invalid input. HTTP 429 reports rate or quota limits. HTTP 5xx indicates an upstream or unexpected server failure.

Recovery rules#

Do not retry all non-success responses. Correct 422 input. Refresh and intentionally repeat a 409 operation with current concurrency fields. Wait for a documented interval on a rate limit. Retry a transient upstream failure only with bounded attempts. Never retry a non-idempotent mutation blindly after an unknown network result.

Operation pages summarize reviewed common and route-declared errors. Those lists are useful starting points but are not exhaustive because errors can also originate in shared validation and core domain logic.

The complete public code inventory is distributed by domain. Start with Errors and recovery, then use authentication errors, model errors, knowledge errors, Workflow and Procedure errors, Test Chat errors, Telegram errors, and quota errors. Each stable code has one canonical home in that index.

Codes are the stable handling key. Messages and details are diagnostic and can include operational identifiers or configuration names. Do not display either value raw to an end user. Map known codes to curated product copy, use field diagnostics only in the appropriate controlled UI, and fall back to a neutral error message.

Logging and escalation#

Log method, path template, status, code, and UTC time. Redact identifiers, configuration names, and customer content from message and details before logging or escalation. Always remove Authorization, Cookie, Secret values, bot tokens, prompts, conversation text, and request bodies containing customer data. Escalate reproducible failures through Support.

For access failures, also read Authentication and Resource scope.