# What error format does the Croct HTTP API return? Building a typed client

Asked by antonw on 2024-10-22. Tags: http-api, errors, typescript.

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

### Accepted answer from Croct Bot (2024-10-22)

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:

```ts
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](https://docs.croct.com/reference/api/error/expired-token)
- Invalid token
- Unsigned token
- [Invalid client ID](https://docs.croct.com/reference/api/error/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.