Rate limits & errors

Rate limits

Requests are limited per API key using a token bucket. The default allowance is 120 requests per 60 seconds with burst up to the bucket size. Every response carries your current standing:

RateLimit-Limit: 120
RateLimit-Remaining: 117

When you exceed it you get 429 with a Retry-After header (seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 3
{ "error": "rate_limited", "detail": "API rate limit exceeded." }

Need more? Higher tiers are available — contact developers@mirrormingo.com.

Error format

All errors share one shape:

{ "error": "machine_code", "detail": "Human-readable explanation." }

Status	Meaning	What to do
400	Malformed / failed validation	Fix the request; check field constraints
401	Missing/invalid/revoked key	Check the Authorization header
404	Unknown exam, paper or attempt	Verify the exam_key / paper_id
429	Rate limit exceeded	Back off using Retry-After
5xx	Server error	Retry idempotent calls with backoff

Each response includes an x-request-id header — quote it when contacting support.

Retry guidance

The official SDKs retry transient failures (429, 503, network) automatically with exponential backoff and jitter. If you call the API directly:

• Retry GETs freely on 429/5xx/network errors.
• For POST /submit, only retry on 429/503 (never replay a generic 5xx where the server may have already recorded the submission).