Idempotency and safe retries

Retry any request without creating a second exam, a duplicate submission or a double charge, using the Idempotency-Key header and the API’s natural keys.

Networks fail. A request can time out after Evalezy has already created the submission, and your retry must not create a second one or charge twice. The API gives you two tools for this:

1. The Idempotency-Key header on POST requests: a retry with the same key returns the first answer instead of running again.
2. Natural keys enforced by the API itself: your external_ref for exams, your external_id for candidates, and one live submission per candidate per exam.

Use both. The header covers every POST; the natural keys protect you even when a retry is sent without it, for example after your own process restarts.

The Idempotency-Key header

Send a unique value, such as a UUID, in the Idempotency-Key header. Reuse the same value for every retry of that request.

curl

curl https://api.evalezy.com/v1/exams/$EXAM_ID/submissions \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Idempotency-Key: 5d2c7a1e-8f3b-4e69-a0d4-1b9c6e2f7a83" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": { "external_id": "STU-2026-0412", "name": "Aarav Sharma", "roll_number": "12" },
    "upload_id": "9e4b1f7a-2c6d-4a83-b5e0-7d1c3f8a6b29"
  }'

Rules

Rule	Detail
Optional	Without the header the request simply runs.
Format	1 to 255 printable ASCII characters. Anything else is 422 validation_failed on the field Idempotency-Key. A UUID v4 is ideal.
Scope	Per institute, not per API key. A retry sent with a rotated key, or from a second key of the same institute, still replays. Never reuse the same value for two different requests anywhere in your institute.
Lifetime	Kept for 48 hours. After that the same value starts a new request.
Same request	The method, the path and the JSON body together identify the request. Key order and whitespace in the body do not matter.

What happens on a retry

Situation	Response
Same key, same request, first call finished	The stored response: same status code and body, plus the header Idempotent-Replayed: true. Nothing runs again and nothing is charged again.
Same key, same request, first call still running	409 request_in_progress with Retry-After: 2. Wait and retry with the same key.
Same key, different request	422 idempotency_key_reused. Generate a new key for the new request.

A replayed error carries a fresh request_id for the retry, not the original one.

Which outcomes are stored

Stored and replayed	Not stored: a retry runs again
Successful responses (2xx)	5xx errors
Most 4xx errors, such as 404 and 422	402 insufficient_credits
	409 conflicts
	429 rate limits and quotas

This means a retry after a 500, a 503 or a 429 really retries, and a retry after topping up credits goes through, while a retry of a successful create gives you back the same resource.

A stored 422 is replayed as long as the request is identical. Once you fix the body it is a different request, so send it with a new Idempotency-Key; the old key would answer 422 idempotency_key_reused.

Endpoints that accept the header

Every POST that creates or changes something:

Endpoint	Natural key, if any
POST /exams	external_ref
POST /exams/{id}/questions
POST /exams/{id}/open
POST /candidates	external_id (upsert)
POST /exams/{id}/candidates	already-registered candidates are reported, not duplicated
POST /uploads
POST /exams/{id}/submissions	one live submission per exam and candidate
POST /submissions/{id}/re-evaluate
POST /submissions/{id}/cancel	cancelling twice is a no-op
POST /submissions/{id}/approve
POST /exams/{id}/finalize
POST /submissions/{id}/unfinalize

The read-only POST lookups (/exams/search, /candidates/search, /credits/quote) are safe to repeat and ignore the header. PUT and PATCH set values, so repeating them gives the same result. A repeated DELETE answers 404, which you can treat as success.

Replays of POST /uploads never contain the upload URLs. Presigned URLs are credentials, so they are not stored. A replayed response lists the same uploads with upload_url_redacted: true and no upload_url. If you lost the URLs, create new uploads with a new Idempotency-Key.

Natural keys

These rules hold whether or not you send an Idempotency-Key.

Exams: external_ref

Give every exam your own reference, for example "external_ref": "CBSE-X-SCI-HY-2026-10A". A second POST /exams with the same external_ref is refused:

{
  "error": {
    "code": "exam_exists",
    "message": "An exam with this external_ref already exists.",
    "request_id": "req_4e1b7c9d2a5f4c8e9b0d3a6f1c2e7b95",
    "details": { "exam_id": "c2a9e4f1-6b3d-4a7e-8c15-9d0f2b7e3a61" }
  }
}

Treat exam_exists as success and continue with details.exam_id. To look exams up by your references without creating anything, call POST /exams/search with up to 500 external_refs. Deleting an exam frees its external_ref for reuse.

Candidates: external_id

Candidates are keyed by your student id, external_id, within your institute. POST /candidates (and inline candidate objects on submissions) upsert: the first call creates the candidate, later calls update the fields you send and keep the ones you leave out. Sending the same candidate twice never creates two.

Submissions: one live submission per candidate per exam

An exam holds at most one live submission per candidate. A second POST /exams/{id}/submissions for the same candidate is refused with 409 submission_exists, and details.submission_id points to the existing one, so a blind retry can never grade a copy twice.

To deliberately replace a copy (for example after a rescan), send "replace": true. The old submission is marked replaced and its grading is cancelled. A finalized submission cannot be replaced until you unfinalize it (409 submission_finalized).

Uploads: used once

Each upload can be attached to one submission only. Reusing it answers 409 upload_already_used with the submission that holds it.

A robust pattern

1. Derive keys from your own records

   Use your exam id as external_ref and your student id as external_id. Retries then line up on their own.

2. Generate one Idempotency-Key per job, store it, reuse it

   Persist the key next to the job in your database before the first attempt, so a restarted worker retries with the same value.

3. Retry only what is retryable

   429, 500, 503 and 409 request_in_progress, honouring Retry-After. See Errors.

4. Treat natural-key conflicts as success

   On exam_exists or submission_exists, read the id from details and carry on.