Errors - Vacademy Docs

Errors use standard HTTP status codes and always return this body:

{
  "error": {
    "code": "invalid_request",
    "message": "page_size must be between 1 and 100.",
    "request_id": "req_3f2a9c1d7e5b4a608f1e2d3c4b5a6978",
    "details": { "param": "page_size" }
  }
}

code is stable. Branch on it.
message is a sentence for logs. Its wording may change.
request_id is also in the X-Request-Id header. Quote it when you contact [email protected].
details is present only when there is more to say (table below).

Error responses carry Cache-Control: no-store.

Codes

HTTP	Code	`details`	What to do
400	`invalid_request`	`param`	Fix the parameter or field it names: a non-numeric `page`, `page_size` outside 1-100, an unknown `sort` or `availability`, an invalid enquiry field. Also returned for malformed JSON.
415	`invalid_request`		Send `POST /leads` with `Content-Type: application/json`.
401	`missing_api_key`		Send the key in `X-API-Key` (or `Authorization: Bearer`).
401	`invalid_api_key`		Not a `vak_pub_` key, or unknown, revoked or expired. Check it in the dashboard.
403	`product_not_enabled`		The key belongs to another Vacademy API. Use a Catalogue API key.
403	`insufficient_scope`	`required_scope`	The key lacks `catalog:read` or `leads:write`.
403	`origin_not_allowed`	`origin`	A browser call from a host that is not a verified website. Verify it, or call from your server. See Keys and websites.
404	`not_found`		No such course or learning path for this institute (not published, or wrong id), or no such endpoint.
405	`method_not_allowed`		Wrong HTTP method for this path.
429	`rate_limited`	`limit_per_minute`	Wait the seconds in `Retry-After`, then retry. See Rate limits.
500	`internal_error`		Retry with backoff. If it persists, contact support with the `request_id`.
503	`auth_unavailable`		Keys could not be checked for a moment. Retry after `Retry-After` seconds (5).

Retrying

Retry 429, 500 and 503 with backoff (respect Retry-After; else 1 s, 2 s, 4 s… up to a minute). Other 4xx errors fail again until the request changes. POST /leads is safe to retry: a repeat of an enquiry that was already saved returns 200 {"status": "duplicate"}.

In browser JavaScript, cross-origin responses do not expose Retry-After or X-Request-Id to your code. Use error.request_id from the body, and wait 60 seconds after a 429 (limits reset each clock minute). Server-side code can read every header.