Errors

Every WAVE API failure returns one normalized shape, generated directly from the gateway's own OpenAPI contract — never a raw upstream error, stack trace, or vendor SDK object.

This page is generated from WAVE Enterprise Streaming Platform API v1.0.0 — 8 named error responses. It is never hand-edited; when the gateway's error catalogue changes, the page regenerates.

See it live

An unpaid, unauthenticated call to any x402-payable route returns the error envelope inline in its 402 body. A malformed call to a plain (non-x402) route returns it as the whole response:

curl -s https://api.wave.online/v1/clips/does-not-exist \
  -H "Authorization: Bearer $WAVE_API_KEY"

The envelope

WAVE-normalized error envelope returned by the api.wave.online gateway. Upstream provider, auth, and quota failures are interpreted into this single shape — raw upstream errors (stack traces, vendor SDK objects) are never leaked to the caller. error.code is a stable machine-readable code (e.g. AUTH_REQUIRED, SCOPE_OVERREACH, RATE_LIMIT_EXCEEDED, UPSTREAM_ERROR); error.message is human-readable.

{
  "error": {
    "code": "SCOPE_OVERREACH",
    "message": "The key lacks the scope for this operation.",
    "suggestions": [
      "Request the missing scope from the developer portal."
    ],
    "doc_url": "https://docs.wave.online/docs/errors"
  }
}

error.code is stable and machine-readable; error.message is safe to show a user; suggestions is written to be acted on by a human or an agent.

Named responses

Response	What it means
`ValidationError`	Validation error
`NotFoundError`	Resource not found
`RateLimitError`	Rate limit exceeded
`Unauthorized`	Authentication required, or the API key / token is invalid or expired.
`Forbidden`	The key is valid but lacks the scope or entitlement for this operation (e.g. SCOPE_OVERREACH, quota tier exhausted).
`PaymentRequired`	Payment required — the gateway answers with an x402 challenge instead of serving the request. This response does NOT use the `Error` envelope. Its `error` member is a plain string (`"payment required"`); the normalized WAVE error object is nested under `error_detail`. Complete the challenge in `accepts[0]` and retry with the `x-payment` header. Observed on `api.wave.online` 2026-07-25: a request with no API key AND a request with an unrecognized API key both receive this 402 (not a 401) on the MoQ mint routes, so a client must treat 402 as the ordinary "not yet authorized to pay-per-use" outcome.
`MoqJoinUnconfigured`	`MOQ_JOIN_UNCONFIGURED` — the mint is fail-closed and the signing secret is not provisioned in this environment. The gateway will never mint an unsigned or empty-key token. Not retryable by the caller; it clears when an operator provisions the secret.
`UpstreamError`	An upstream capability provider (e.g. the speech engine) failed. The gateway interprets the failure and returns this normalized WAVE error instead of the raw upstream response, so the caller always sees a stable shape it can act on.

The x402 challenge is a different shape

A 402 Payment Required response does not use the envelope above. Its error field is a plain string; the normalized error object is nested under error_detail. See Agent commerce for the full challenge captured live.