Handle errors, quotas, and retries

Every API failure uses JSON and includes a support-safe request identifier. Branch on HTTP status and stable error.code, not on translated message text.

{
  "error": {
    "code": "student_not_found",
    "message": "Student not found",
    "request_id": "req_example",
    "details": null
  }
}

Status classes

Status	Meaning	Client action
`400`	Invalid query, malformed JSON, or invalid idempotency header	Correct the request
`401`	Missing or invalid credential	Stop and replace or fix the key
`403`	Scope, rollout, feature, suspension, network, or policy denial	Obtain authorized configuration
`404`	Route or tenant-safe resource not found	Verify the documented route and local identifier
`409`	Lifecycle or idempotency conflict	Inspect the code; retry only when documented
`413`	Body exceeds 1 MiB	Reduce the request
`415`	Unsupported media type	Send JSON
`422`	Valid JSON with invalid business fields	Correct the data
`429`	Burst or daily quota reached	Respect `Retry-After`
`500`	Unexpected server failure	Retry cautiously and report the request ID
`503`	API, policy, quota, or another required service unavailable	Back off and retry later

Do not use 404 to infer whether an identifier belongs to another school.

Rate-limit headers

After quota evaluation, responses include:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Reset is the next midnight UTC as a Unix timestamp. -1 for limit and remaining means unlimited, but usage can still be metered. A 429 includes Retry-After. The current Enterprise default is 10,000 requests per UTC day unless an effective override applies.

Retry policy

Never loop on 400, 401, 403, 404, 413, 415, or 422.
For 409 idempotency_request_in_progress, wait for Retry-After and resend the identical request and key.
For 429 or 503, use bounded exponential backoff with jitter and respect Retry-After.
Retry an uncertain write only with its original idempotency value and exact request.
Cap attempts and surface a durable failed job for operator review.

Ask for support safely

Provide the timestamp, endpoint template, HTTP status, stable error code, and request_id. Do not provide the bearer credential, authorization header, raw idempotency value, full request body, or personal-data response.

See idempotent writes and troubleshooting the API.