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.

403tier_upgrade_requiredDiagnostic Code: ERR_TIER_UPGRADE_REQUIRED. Trial credits for higher API layers (L2–L4) are exhausted. Upgrade to Developer or Growth plan to unlock production volume.

403quota_exceededDiagnostic Code: ERR_QUOTA_EXCEEDED. Monthly subscription or add-on credit balance has been fully consumed. Upgrade plan or purchase credit top-ups.

403email_verification_requiredDiagnostic Code: ERR_EMAIL_VERIFICATION_REQUIRED. Unverified email sandbox credit cap (100 credits) reached. Verify developer email to unlock full 1,000 monthly credits.

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"
  }
}