Errors

Errors are JSON with an error code and a readable detail:

{ "error": "bad_request", "detail": "Expected exactly 3 winners, got 2." }

Status	Code	Meaning
400	bad_request	The request is wrong: not JSON, the wrong number of winners, a repeated winner, a bad name or avatar, or an unknown status filter.
401	unauthorized	No key, or an unknown or revoked one.
404	not_found	No such campaign, drawing or guarantee under your account.
409	locked	The cutoff has passed and this list differs from the locked one.
409	pull_campaign	Prizerail fetches this campaign’s winners from your URL.
409	campaign_ended	The campaign has ended and takes no more winners.
400 or 409	rejected	The guarantee pick isn’t allowed. See Guarantees.

The detail is written for people, so it’s fine to log or show to your team. Match on error, which won’t change.

Retries

• A 5xx or a network error means Prizerail didn’t finish the request. Retry it with a growing wait, say 10 seconds, then a minute, for up to 10 minutes. Every call is safe to repeat: sending the same winners again returns 200, and reading never changes anything.
• There’s no rate limit today. If you ever get a 429, wait for the seconds in its Retry-After header before trying again. Polling once a minute per campaign is plenty, since drawings change state on a 5-minute cycle.
• The API is versioned by its path, /api/v1. Within v1, fields are added but never removed or renamed. Changes are listed in the changelog.