Error Handling

Handle RelayAPI errors, request limits, idempotent retries, and uncertain provider outcomes safely.

Error envelope

API errors use one JSON envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "issues": [
        {
          "code": "too_small",
          "message": "Content is required",
          "path": ["content"]
        }
      ]
    }
  }
}

details is optional. Branch on error.code; do not parse the human-readable message.

HTTP status codes

Common error codes

Provider-specific failures use a specific code where possible. Treat the HTTP status and the documented provider disposition as authoritative rather than assuming every provider error is safe to replay.

Buffered request limits

RelayAPI checks both a trustworthy Content-Length and the bytes received from an unknown-length or chunked body.

An inaccurate or omitted Content-Length does not bypass the limit. Do not compress buffered authenticated JSON or the two multipart envelopes; send Content-Encoding: identity or omit the header.

Upstream response containment

RelayAPI independently caps publisher-provider JSON and diagnostic text that it materializes inside the API Worker at 2 MiB. An oversized or malformed provider response fails closed as an upstream/provider error; it is not a client request-envelope 413. Streamed provider media keeps its route-specific streaming and byte limits.

Safe retries

Reads can normally retry 429, 502, 503, and 504 with exponential backoff and jitter. Always honor Retry-After when present.

Mutations require more care:

1. Generate one Idempotency-Key for the logical operation.
2. Reuse the same key and exact body bytes for every attempt.
3. Never switch to a new key merely because a request timed out or returned 500/502.
4. If RelayAPI returns IDEMPOTENCY_IN_PROGRESS, wait for Retry-After and retry the same request.
5. If it returns IDEMPOTENCY_OUTCOME_UNKNOWN, stop automatic retries and reconcile the resource/provider state.

The same rule applies to asynchronous operation resources whose status becomes unknown. In particular, a TikTok/X ad-report submission or provider-backed social mutation may have crossed the provider boundary before a response was lost. Poll the existing operation and use its documented recovery path; do not create a second logical operation with a new idempotency key.

Published edits, social actions, and WhatsApp administration return their durable operation even when its embedded status is failed or unknown. Inspect that field; an HTTP success/acceptance response means the operation resource was returned, not necessarily that the provider mutation completed.

async function retryRead(url: string, apiKey: string, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (![429, 502, 503, 504].includes(response.status)) return response;
    if (attempt === attempts - 1) return response;

    const retryAfter = Number(response.headers.get('Retry-After'));
    const baseMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : Math.min(30_000, 500 * 2 ** attempt);
    await new Promise((resolve) =>
      setTimeout(resolve, baseMs + Math.random() * 250),
    );
  }

  throw new Error('unreachable');
}

Logging

Log the HTTP status, error.code, request ID/correlation headers, route, and your own idempotency key. Do not log bearer tokens, OAuth codes, webhook URLs, provider tokens, raw credentials, or sensitive request bodies.