Error Codes Reference

Reference for HTTP status codes, error payloads, and diagnostic codes returned by the ALOC API.

3.1.0Overview

All API error responses follow a consistent format. They include a standard HTTP status code and a JSON response body containing an error identifier and a human-readable message:

Example Error Payload

{
  "error": "unauthorized",
  "message": "Invalid API key format."
}

3.1.1Error Codes Reference

The following table documents all unique error conditions that may occur:

STATUSCODEDESCRIPTION / TYPICAL CAUSE

400bad_requestMissing required filter parameters on index queries (subject, examType, or year).

401unauthorizedMissing or invalid X-API-Key header, or malformed key format.

403forbiddenSandbox credits exhausted, billing credit quota exceeded, session expired, or route requires a higher plan tier.

404not_foundRequested question/session UUID not found, or filters returned no matching questions.

422validation_errorRequest payload inputs failed validation rules (e.g. invalid types or limits).

429rate_limitedSliding window request threshold exceeded. Respect the Retry-After response header.

503ai_unavailableIntelligence or explanation microservice is temporarily down or failed to reply.

3.1.2Reporting Content Errors

If you discover typographical mistakes, wrong keys, or errors in a question or explanation, you can flag it using the content reporting endpoint:

POST/questions/{id}/report

FIELDTYPEREQUIREDDESCRIPTION

messagestringyesDescription of the issue (minimum 5 characters).

typeenumyesquestion, option_[a-e], correct_answer, explanation, other.

reporterNamestringnoName of developer reporting the issue.

201 Created Response

{
  "message": "We have received your report on this question. Thank you.",
  "data": {
    "reportId": 14,
    "status": "pending"
  }
}