Errors

Every error response has the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: student.external_id.",
    "param": "student.external_id",
    "resource_id": null,
    "request_id": "3f2b8c1e-9d4a-4e7b-a6c5-1f0e2d3c4b5a"
  }
}

Field	Meaning
type	The broad category, from the table below.
code	A stable, specific code to branch on. The full list is in Appendix A.
message	A human-readable explanation. Its wording can change, so don’t parse it.
param	The request field at fault, when there is one. Otherwise null.
resource_id	For submission_exists and external_id_taken, the ID of the object that already exists. Otherwise null.
request_id	The same value as the X-Request-Id header.

HTTP status	type	When
400	invalid_request_error	A parameter is missing, invalid or unknown.
401	authentication_error	The key is missing, invalid or revoked.
402	billing_error	Not enough credits, or your credits have expired.
403	permission_error	The key lacks a scope, the IP is not allowed, or the account is suspended.
404	invalid_request_error	The object doesn’t exist, or belongs to the other mode.
409	invalid_request_error	The object’s state doesn’t allow this, or an idempotency conflict.
413	invalid_request_error	The request body is over 1 MB.
415	invalid_request_error	The request body isn’t JSON, or is compressed.
429	rate_limit_error	Too many requests. See Rate limits.
500, 503	api_error	A problem on our side.

When to retry

Retry with the same Idempotency-Key	Fix first, then retry	Don’t retry
Network errors and timeouts	400, 401, 403, 413	404
409 idempotency_request_in_progress, after a second	402, after topping up	409 submission_exists: the submission is already there, at resource_id
409 paper_not_ready, once the paper is ready		Any other 409 without changing something first
429, after Retry-After
500, 502, 503, 504

Retry with exponential backoff and jitter, for example 1 s, 2 s, 4 s, up to 60 s. Errors are never saved against an idempotency key (see Idempotency), so retrying with the same key is always safe.

Problems found after a create request succeeds, such as an unreadable script, are not HTTP errors. They appear on the object as status: "failed" with a failure object, and in a paper.failed or submission.failed webhook.