Errors

One error shape everywhere, stable codes and what to do about each status.

The error shape

JSON

{
  "error": {
    "code": "QUESTION_COUNT_TOO_HIGH",
    "message": "Ask for up to 20 questions per request; send another request for more.",
    "request_id": "req_7Hq2…",
    "docs_url": "https://developers.edumark.ai/docs/guides/errors"
  }
}

Branch on code, show message to people, and quote request_id (also in the X-Request-ID header) when you contact support. Failed requests and failed jobs are never charged.

When the body does not match the schema (a missing field, a wrong type, an unknown field), the answer is 422 API_INVALID_REQUEST and error.fields lists each problem: field is its path, such as body.count, and type says what is wrong.

A schema problemJSON

{
  "error": {
    "code": "API_INVALID_REQUEST",
    "message": "Check the request fields against the API schema.",
    "fields": [{ "field": "body.count", "type": "int_parsing" }],
    "request_id": "req_9Lm4…",
    "docs_url": "https://developers.edumark.ai/docs/guides/errors"
  }
}

Status codes

Status	What happened	What to do
400	The request was malformed.	Fix the request.
401	The key is missing, wrong, expired or revoked.	Check the key.
402	Your API balance or monthly limit cannot cover the job (`API_BALANCE_TOO_LOW`, `API_SPEND_LIMIT_REACHED`).	Top up, switch on credits, or raise the limit.
403	The key lacks the scope, or its sponsor lacks the EduMark permission.	Add the scope or the permission.
404	Not found in this key’s centre.	Check the id and the key’s centre.
409	An Idempotency-Key was reused with a different body.	Use a new key for new work.
413	The request or file is too large.	Upload with POST /v1/files.
422	The request failed a check. Schema problems (`API_INVALID_REQUEST`) list each field in `error.fields`; other checks, such as `QUESTION_COUNT_TOO_HIGH`, give a code and message.	Fix the request.
429	Too many requests.	Wait `Retry-After` seconds.
503	Temporarily unavailable.	Retry with backoff.

Retrying safely

Retry 429, 503 and network errors with exponential backoff. For a POST, resend the same body with the same Idempotency-Key: you get the original job back rather than a second one, and you are only charged once.

NextRate limits