Does SkedCast's API return RFC 9457 problem+json errors?

Yes. Every error response is application/problem+json with a type URL that opens a documentation page.

How should I handle an error?

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.

What does the action field on an error mean?

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.

Error catalogue: problem+json (RFC 9457)

Browse docs

5 min read

POST /v1/postsREST · OpenAPI · MCP

bash

curl -X POST https://api.skedcast.com/v1/posts \
  -H "Authorization: Bearer sked_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "clientId": "6d58a0f2-1c3e-4b7a-9f21-0a1b2c3d4e5f",
    "content": "New drop is live 🔥",
    "targets": { "mode": "group", "clientId": "6d58a0f2-1c3e-4b7a-9f21-0a1b2c3d4e5f" },
    "schedule": { "type": "at", "scheduledAt": "2030-01-15T15:00:00Z" }
  }'

json

{
  "data": {
    "postId": "f27e6cf1-8b2b-4c1a-9c0e-6a2b7e8f1d3a",
    "status": "scheduled",
    "targetCount": 24
  },
  "meta": { "correlationId": "c-74fb602e-…" }
}

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.

jsonapirfc 9457error handling

FAQ

Does SkedCast's API return RFC 9457 problem+json errors?: Yes. Every error response is application/problem+json with a type URL that opens a documentation page.
How should I handle an error?: 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.
What does the action field on an error mean?: 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.

Error catalogue (JSON)

Anatomy of an error#

An example response#

What each field means#

FAQ

Ready to broadcast everywhere?