Errors

Envelope

{
  "error": {
    "type":    "validation_error",
    "code":    "invalid_message_request",
    "message": "to is required.",
    "param":   "to",
    "request_id": "req_...",
    "trace_id":   "trc_..."
  }
}

type is the category (stable). code is the specific reason (also stable; treat it as a string). message is human-readable and may change. param is set on validation errors. Rate-limit errors also include retry_after_ms. trace_id is the single field to include in a support ticket.

Reporting an unexpected failure

When a public /v1/* call fails with an unhandled internal_error — something genuinely unexpected on our side, not a typed operational error — the envelope carries an additive, optional feedback pointer telling an integrating agent where to report it:

{
  "error": {
    "type":    "internal_error",
    "code":    "internal_error",
    "message": "An internal error occurred.",
    "request_id": "req_...",
    "trace_id":   "trc_...",
    "feedback": { "endpoint": "/v1/feedback", "method": "POST" }
  }
}

Post the trace_id (and, if you have it, the request_id and the code) to POST /v1/feedback as the related_error so the report correlates to the failure. The endpoint is a constant relative path — always /v1/feedback, never derived from the request host.

The pointer is deliberately narrow. It appears only on an unhandled internal_error from a public /v1/* route that is not /v1/feedback itself. It is absent from every 4xx, from typed operational 5xx such as provider_error, from rate-limit and idempotency responses, and from all dashboard errors. The field is additive, so an older SDK that does not know about it simply ignores it. See the /api-reference/feedback page for the request shape and the receipt.

Discovering the API from an error

When a request’s method and path match no route at all, the answer is a 404 whose code is route_not_found— and on a public /v1/* path that envelope also carries an additive, optional discovery pointer naming the two documents an agent can read to find what the API actually serves:

{
  "error": {
    "type":    "not_found",
    "code":    "route_not_found",
    "message": "No route matches GET /v1/mesages.",
    "request_id": "req_...",
    "trace_id":   "trc_...",
    "discovery": {
      "openapi":    "/openapi.json",
      "well_known": "/.well-known/tyxter.json"
    }
  }
}

Check the path you called against /openapi.json, which lists every operation the API serves; /.well-known/tyxter.jsonis the capability manifest — the API, dashboard, and docs base URLs plus what the platform offers and where each capability is documented. The messagenames the method and the path we matched against, with the query string stripped — a key you accidentally put in the URL is never echoed back to you. Both pointer values are constant relative paths on the API host, never derived from the request host.

The pointer is as narrow as the feedback one. It appears only on route_not_found, and only for /v1/*targets — never on any other error, and never on a dashboard or BFF route. The field is additive, so an older SDK that does not know about it simply ignores it. route_not_found is a statement about the path, not about a record: a route that exists whose resource does not still answers its own code, such as message_not_found. It is unrelated to llm_route_not_found, which means no LLM route is configured for the environment.

Framework-level refusals arrive in the same envelope. A malformed JSON body on a route that expects JSON answers http_exception with the typechosen from the status — so a 400 reports validation_error, never internal_error — and a body over the route’s size limit answers payload_too_large whether the size was declared up front or only discovered mid-stream.

Categories

Common codes worth handling explicitly

Transcription recovery

POST /v1/messages/{message_id}/transcription is an opt-in create operation, not a retry endpoint. invalid_transcription_request and transcription_source_not_audio are 400 validation errors: correct the request or use a stored inbound WhatsApp audio message. media_asset_expired is also a 400, but means the exact original consumed audio was valid and its retention window elapsed. A provider failure happens after acceptance and appears as a failed transcript receipt; it is not one of those request-time source errors. If the source is inbound audio whose media descriptor is still downloading, wait until its status reaches consumed before retrying create.

A pending or succeeded receipt created with a different language hint returns 409 transcription_language_conflict. Omit the hint or send the original two-letter language to replay that receipt; the create operation will not replace its language intent.

A create request that finds a failed receipt returns 409 transcription_retry_required. Use POST /v1/messages/{message_id}/transcription/retry with a non-blank Idempotency-Key. Missing it returns 400 idempotency_key_required; the same key with a different body returns 409 idempotency_key_conflict. Reuse the same key and body only to replay the stored 202. A pending receipt returns transcription_in_progress, a succeeded receipt returns transcription_already_completed, and a structurally unavailable original source returns transcription_source_unavailable; none is fixed by substituting another attachment. A retry with no receipt first returns 404 transcription_not_found — create it with the original route.

429 transcription_retry_rate_limited means the manual retry cooldown or rolling generation cap is active. Wait for both error.retry_after_ms and Retry-After, then replay the same logical retry command with the same Idempotency-Key. Use a fresh key only for a distinct retry command.

An accepted BYOK run that cannot use its pinned configuration fails closed with stt_provider_config_not_found, stt_provider_config_disconnected, stt_provider_config_invalid, or stt_provider_credential_unreadable. Missing effective pricing is reported as transcription_billing_rate_unavailable. These terminal receipt codes perform no provider call, emit no usage, and never move a run that is already using your key onto Tyxter’s credential. Fix the configuration or pricing condition, then create a distinct manual retry.

Two terminal receipt codes are not about your credential at all. transcription_failed is the residual provider outcome: Tyxter retried and the provider still returned no transcript, including the case where the audio is larger than the provider accepts. transcription_not_configured means the environment has no transcription credential to run on at all — neither an override of yours nor a platform credential. Neither charges you for a transcript. The first is worth a distinct manual retry; the second is not, until the environment is configured.

stt_provider_config_disconnectedreaches only a transcription that was already attributed to the key you disconnected. Disconnecting withdraws your override, so every transcription that was not — including one still queued — runs on Tyxter’s platform credential and its stt.audio.second meter instead. stt_provider_config_invalid and stt_provider_credential_unreadable are different: the key is still there but unusable, so they keep failing closed until you rotate or replace it.

During the two-phase BYOK rollout, public openai.stt credential setup can return 503 transcription_byok_runtime_inactive before validation, persistence, or provider work. Retry the unchanged request with the same Idempotency-Key after activation. Dashboard STT writes can return 409 stt_provider_config_busy when their bounded configuration-lock wait expires; retry the exact same command with the same Idempotency-Key. Neither condition is permission to change the credential payload during replay.

Provider credential setup sessions

The hosted credential setup flow (POST /v1/provider-credential-setup-sessions and its complete/deny/get routes) has a small lifecycle vocabulary. An unknown or foreign-tenant session id returns 404 provider_credential_setup_session_not_found. A session past its deadline returns 409 provider_credential_setup_session_expired — create a new session rather than replaying the old link. Completing or denying a session that already finished returns 409 provider_credential_setup_session_already_completed or 409 provider_credential_setup_session_already_denied, and completing one the customer denied returns 409 provider_credential_setup_session_denied; none of these change state, so read the session to see where it landed. Completing a session whose target the environment no longer has configured returns 409 provider_credential_setup_target_not_configured. Creating an openai.stt setup session on a sandbox environment returns 400 provider_credential_setup_stt_sandbox_unsupported — sandbox transcription is simulated and never uses a customer credential.

Retry guidance

• Treat 5xx and network errors as retryable. Use an idempotency-key on write paths that accept one — check /openapi.json, where an operation that honors the header declares an idempotency-key header parameter.
• Never retry 4xx without fixing the request — you'll just burn rate-limit tokens.
• 429 responses include Retry-After in seconds and error.retry_after_ms in the body. Honor it; a fixed short sleep will cause cascading retries.