Errors and retries

Errors are RFC 9457 problem details, as application/problem+json. Act on the status and type, which is stable for each kind of error, such as https://api.dizplai.com/problems/unknown-option. title and detail are for logs and can change.

{
  "type": "https://api.dizplai.com/problems/unknown-option",
  "title": "Unknown option",
  "status": 400,
  "detail": "opt_01M7WQND9RKTH6WF72R2VFKZ1S is not an option of this poll.",
  "request_id": "f3b1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

request_id matches the x-request-id header on every response. Quote it when you report an issue.

Status	Means	Retry?
`400`	The request is invalid, such as an unknown option or a widget not live	No. Fix the request
`401`	A missing, invalid or expired key or token	Once, with a fresh token
`403`	Not allowed for this caller or fan	No
`404`	Not found	No
`409`	An `Idempotency-Key` reused within 24 hours with a different body	No. Use a new key for a new request
`429`	Over your usage plan	After `Retry-After` seconds
`503`	Writes can’t be taken right now	After `Retry-After` seconds

Votes are safe to retry. A vote counts once per fan and widget: a repeat, even with a different choice, is accepted and never counted. Creates take an Idempotency-Key. Send a unique one with each create, and the same one on its retries, so a retry never creates twice.

Introduction

Guides