Parlay App API

Every error has the same shape. Branch on code, which is stable. message is for people and may change.

{
  "error": {
    "code": "rate_limited",
    "message": "Request limit exceeded.",
    "request_id": "req_4f1b2c9e-7d0a-4b8e-9a51-2f6c0e3d1a77"
  }
}

The same request_id is in the X-Request-Id response header. Include it when you contact support.

Error codes

Status	Code	Meaning	What to do
400	`invalid_request`	A parameter is missing or invalid	Fix the request. Do not retry unchanged.
400	`permission_unavailable`	Settings only: that permission isn’t available yet	Choose read permissions only.
401	`unauthorized`	The key is missing, malformed, expired or revoked	Check the key. Create a new one if it was revoked or expired.
403	`forbidden`	The key lacks a permission this endpoint needs	Create a key with the needed permission.
403	`transcript_consent_required`	Settings only: transcript access needs the disclosure accepted	Accept the disclosure when creating the key.
404	`not_found`	The resource does not exist or is outside your organization	Check the id. A call from another organization also returns this.
404	`no_transcript`	The call has no transcript yet	Wait for `call.transcript.ready`, or retry later.
409	`stale_cursor`	The transcript changed while you were paging it	Start the transcript from the first page.
413	`payload_too_large`	The request body is too large	Send a smaller body.
415	`unsupported_media_type`	The body is not `application/json`	Set `Content-Type: application/json`.
422	`content_unavailable`	This item has stored data the API can’t return	Skip it. Retrying won’t help.
429	`rate_limited`	A rate limit was reached	Wait for `Retry-After` seconds, then retry.
503	`temporarily_unavailable`	Parlay could not complete the request right now	Retry with backoff.

Retrying safely

Retry only 429, 503 and network errors. Use exponential backoff with jitter, and honor Retry-After when it is present.

async function withRetry(fn, attempts = 5) {
  for (let i = 0; ; i++) {
    const res = await fn();
    if (res.status !== 429 && res.status !== 503) return res;
    if (i === attempts - 1) return res;
    const wait = Number(res.headers.get("retry-after")) || 2 ** i;
    await new Promise((r) => setTimeout(r, (wait + Math.random()) * 1000));
  }
}