Errors

Every refusal has one shape:

{
  "error": {
    "type": "AttemptNotFinished",
    "message": "the attempt is not finished"
  }
}

• type is a fixed name. Branch on it.
• message is for a person. It may change, so never parse it. It never names a token.

Every error type

This table is generated from the API’s own list when the docs are built, so it is always complete.

Status	Error types	What it means
400	BadRequest, ServerFieldSupplied	The body fails its schema, or sends a field the server owns.
401	NotSignedIn, Unauthorized	The route needs a credential and the request has none, or a wrong one.
404	NotFound	No such record, or one in another pod. Never 403.
409	AccountMissing, AttemptClaimed, AttemptPreview, AssignmentClosed, AttemptFinished, AttemptNotFinished, AttemptPaused, QuestionNotOpen, TryOutOfOrder, AnswerConflict, EventIdMismatch, WriteOnce	The request conflicts with what is already stored.
429	AnswerLimit	The request is past a limit.
502	BankUnavailable	An upstream the server calls, the question bank, did not answer.

What to do

• 400: fix the request. message names the first field that failed, as field: problem. A body over 16,384 bytes is 400 too.
• 401: send the right credential. See Authentication.
• 404: check the id. A record in another pod is 404, never 403, so the API never says whether it exists.
• 409: read the record again and act on what it says now. An attempt that is paused, finished or claimed refuses a write that no longer fits.
• 429: the attempt is past a limit, such as 200 answers. Start a new attempt.
• 502: the question bank did not answer. Try again later.

A 500 is not on this list. It means the API failed on its side. Try the request again later.