API error codes

TL;DR: Every refusal has the body { "error": { type, code, message, param, requestId, docUrl, retryable } }. This page describes each field, then lists each code, the HTTP status it is sent with and what the caller should do.

The error body

{
  "error": {
    "code": "invalid_request",
    "docUrl": "https://mmw-docs.apidocumentation.com/errors#invalid_request",
    "message": "Invalid request. answers.0.questionId: Too small: expected string to have >=1 characters",
    "param": "answers.0.questionId",
    "requestId": "8f14e45f-ceea-467f-a8d4-b8e6a1c2b6f3",
    "retryable": false,
    "type": "invalid_request_error"
  }
}
Field What it holds
code What went wrong, as a stable code to branch on.
docUrl The code's entry on the public error-code page.
message What went wrong, for a developer to read. It may change.
param The dotted path of the first request field that was wrong, such as answers.0.questionId, or null when no one field was.
requestId The id of this request, the same as the request-id response header. Quote it to MMW about a failure.
retryable Whether sending the same request again may succeed.
type The family of the error, by HTTP status.

Codes

invalid_request is sent with 400, and with 422 when the request is well formed and the data refuses it. A code marked retryable may succeed if the same request is sent again. Each code below is the target of the docUrl of an error with that code.

Code Status Type Retryable What to do
agent_not_allowed 403 permission_error No Stop: an API key or script never corrects, approves or releases a mark, or acknowledges a safeguarding flag. A signed-in teacher or school admin does it in the app. A teacher's connected assistant starts an upload and reads a class set's status and counts, and nothing else.
ai_off 409 conflict_error No Do not retry. The school has turned AI off, so nothing of its work is sent to a model; ask the school's admin.
answer_key_not_confirmed 409 conflict_error No Do not retry as is. A person reads the answer key and confirms it (a new key with confirmed: true); mark with that key.
changed_since_approved 409 conflict_error No Read the submission again, have the teacher approve the marks as they are now, then release.
consent_missing 409 conflict_error No Do not retry. The school has not given the consent this needs; ask the school's admin.
dependency_unavailable 503 api_error Yes Wait, then send the same request again with the same Idempotency-Key.
entitlement_missing 402 permission_error No Ask the school's admin for a current content grant that lists the programme, then send the request again.
file_too_large 413 invalid_request_error No Send a smaller body or file. A request body is at most 1 MiB and an uploaded file at most 25 MB.
idempotency_key_in_use 409 conflict_error Yes Another request with this Idempotency-Key is still running. Wait, then send the same request again.
idempotency_key_reused 422 invalid_request_error No This Idempotency-Key was used for a different request or by a different caller. Use a new key for a new request.
internal_error 500 api_error No Something failed on our side. Tell MMW the request-id response header; a create is safe to send again with the same Idempotency-Key.
invalid_request 400 invalid_request_error No Fix the request as the message says, then send it again. With 422 the request is well formed and the data refuses it.
lease_expired 409 conflict_error Yes The job ran out of time. Create it again.
not_found 404 not_found_error No Check the id. An object in another organisation is answered the same as one that does not exist.
not_invited 403 permission_error No Ask an admin of your organisation to invite the email you signed in with.
parity_required 409 conflict_error No Do not retry. Record a passing parity result for the programme's current rubric, model, adapter and prompt first; nothing else marks it ready for migration.
permission_denied 403 permission_error No Do not retry. The caller's role, or the grants a school has given its organisation, do not allow this.
provenance_mismatch 409 conflict_error No Check the marker's model, adapter and prompt against the job's pinned binding before requesting a new run.
rate_limited 429 rate_limit_error Yes Slow down, then send the request again.
revision_conflict 409 conflict_error No The object changed since you read it. Read it again and repeat the change.
safeguarding_flag_open 409 conflict_error No The school's safeguarding contact must acknowledge the open flag before these marks can be released.
safety_check_pending 409 conflict_error No Wait for the safety check on this submission to succeed, then release.
session_expired 401 authentication_error No Send a valid credential: a person signs in again, and a server sends an API key that has not been revoked.
student_locked 403 permission_error No The student asks their teacher to reset their PIN.
unsupported_file_type 415 invalid_request_error No Send a JPEG, PNG, WebP or PDF file.