# Error catalogue (JSON)
URL: https://skedcast.com/developers/data/api-error-catalogue

Every SkedCast API error is returned as `application/problem+json` (RFC 9457) with a stable `code`, an HTTP `status`, a `category`, and a `type` URL that opens a documentation page. `/developers/data/api-error-catalogue.json` lists every public error in one machine-readable file.

## Anatomy of an error
Every error follows the RFC 9457 shape: a `type` URL that identifies the kind of error, a `title`, a `status` that matches the HTTP status, and a `detail` sentence. SkedCast adds `code` (the stable identifier), `category`, `severity` and, where relevant, `action` (a recovery hint such as `reconnect`, `upgrade` or `retry`) and `correlationId` for support requests.
The `type` URL always opens a documentation page at `https://skedcast.com/errors/{code}`, as RFC 9457 §3.1.1 recommends.

## An example response
```json
{
  "type": "https://skedcast.com/errors/unauthenticated",
  "title": "Authentication required",
  "status": 401,
  "detail": "You need to sign in to do that.",
  "code": "unauthenticated",
  "category": "auth",
  "severity": "error",
  "action": "login",
  "correlationId": "c7f1e2a0-…"
}
```

## What each field means
Field | Meaning
`type` | A URL that opens the documentation page for the error.
`code` | The stable identifier. Branch on it, not on `title` or `detail`.
`status` | The HTTP status code. The catalogue file calls it `httpStatus`.
`title` | A short name for the kind of error.
`detail` | The default message. A response can carry a more specific one.
`severity` | How serious the error is, for example `error`.
`retryable` | `true` when the same request can succeed later: wait, then retry. Catalogue file only.
`category` | One of 8 categories: `auth`, `forbidden`, `not-found`, `conflict`, `bad-body`, `rate-limit`, `retry`, `internal`.
`action` | A recovery hint your code (or an agent) can act on, when one applies.
`correlationId` | The request's trace id. Include it when you contact support. Responses carry it; the catalogue file does not.

## What the catalogue lists
The catalogue lists the errors your integration can receive.

## FAQ
**Q: Does SkedCast's API return RFC 9457 problem+json errors?**
A: Yes. Every error response is application/problem+json with a type URL that opens a documentation page.

**Q: How should I handle an error?**
A: Branch on code, not on title or detail, because the sentences can be reworded. Use action as a hint for recovery, and send correlationId to support if you need help.

**Q: What does the action field on an error mean?**
A: A recovery hint a client can act on programmatically: for example login, reconnect, upgrade, verify-email, mfa, retry, or contact-support. It comes from the same catalogue entry as the error's documentation.