Developer documentation
Errors and safe retries
Handle every documented status without accidentally duplicating a billable POST.
- Audience
- Backend developers and operators
- Before you start
- Logging that records status, error code, and response headers without recording raw keys
Error shape
{
"error": {
"code": "invalid_request",
"message": "Unknown topic 'addition' for grade 'grade3'"
}
}Branch on status and error.code; message is human diagnostic text and may change. Handled errors use this shape. An unhandled infrastructure failure may return a generic 5xx or a non-JSON body.
Decision table
| Status | Typical codes | Action |
|---|---|---|
| 400 | invalid_request | Fix JSON, catalog ids, difficulty, or limits. Do not retry the unchanged payload. |
| 401 | invalid_api_key | Check the header and rotate a revoked key. Do not retry without changing credentials. |
| 402 | insufficient_credits | Add credits or reduce work; do not retry automatically. |
| 403 | org_not_enabled | Activate the correct context or contact the administrator/support. |
| 429 | rate_limited or quota_exceeded | Honor Retry-After when present. A plan cap requires new capacity, not merely a short wait. |
| 502 | upstream_error | Retry with exponential backoff and jitter only when potential duplication is acceptable. |
| Other 5xx | Envelope may be absent | Treat as transient, record status and timestamp, and escalate if persistent. |
Retry policy
- GET /catalog consumes no credits and is safe to repeat after a transient failure.
- For a burst 429, wait at least Retry-After. For 502 or other 5xx, use jittered delays such as 1s, 2s, and 4s with a small attempt cap.
- Set request timeouts and a total retry budget. Open a circuit or degrade the feature when failures persist; do not build an unbounded retry queue.
After an ambiguous outcome, do not automatically repeat a POST unless your product can accept duplicate output and usage. Record your own job id, send state, timestamp, and header changes for reconciliation; that job id does not alter API behavior.
Safe diagnostics
For help, send admin@overthemathwall.com: method and path, UTC timestamp, status, error.code, usage headers, and the visible key prefix. Never send the complete key, passwords, payment-card data, or student personal data.