Skip to main content
Free academy website with paid plans.

Working with the API

Errors and request IDs

The shared error shape, every error type with its HTTP status, and the X-Request-Id header.

Updated

Browse the developer docs

Steps

  1. Read the X-Request-Id header on every response. It is req_ followed by 32 hex characters. Include it when you contact support.
  2. Branch on error.type, not on the message. Errors have the shape { "error": { "type", "message", "detail" (optional), "request_id" } }.
  3. Map types to statuses: invalid_request 400, unauthorized 401, forbidden 403, not_found 404, method_not_allowed 405, conflict 409, idempotency_conflict 422, rate_limited 429, internal 500.
  4. Retry 409, 429 and 500 later. For 429, wait for the Retry-After header. Fix the request or the credential before you retry a 400, 401, 403, 404, 405 or 422.

Notes

  • A path that exists under another method returns 405. An unknown path returns 404 with a message that starts with "no such resource".
  • A write body that is not valid JSON returns 400 "request body must be valid JSON".
  • Unexpected server faults always return type internal with the message "internal error" and no details.
  • A student id that does not exist in your academy returns 404 "no such student". An id that is not a UUID returns 400.
  • When a tool run under /v1/tools fails, the body is { "error": { "type", "message" } } with type unknown_tool (404), forbidden (403) or failed (422).

Related guides

Still need help?

Email hello@chesscore.io. Using ChessCore day to day? Visit the Help centre.