What error format does the Croct HTTP API return? Building a typed client
Writing a thin typed client for the Content and Evaluation APIs. Need the error envelope. Is it consistent across endpoints or per-endpoint shapes?
Want to model it once. Guessing from responses is not a spec
1 answer
Errors follow RFC 9457 (problem details for HTTP APIs) across the whole API, so a single problem-details type covers every endpoint. Responses come back as application/problem+json with the standard type, title, status, and detail members.
A minimal TypeScript model:
interface ProblemDetails { type: string; title: string; status: number; detail?: string;}Documented error cases worth handling explicitly, since they map to distinct recovery strategies:
- Expired token
- Invalid token
- Unsigned token
- Invalid client ID
- Missing client ID
The token errors mean re-issuing the user token; the client ID errors mean the X-Client-Id header is absent or malformed. Everything else you can treat generically through the problem-details envelope. Discriminate on the type URI rather than parsing title strings, that is what it is for.