Errors

When a request fails, the API answers with an HTTP status and a body in the RFC 9457 format, Content-Type: application/problem+json:

{
  "type": "https://getrefract.app/developers/errors/insufficient-scope",
  "title": "The credential does not grant the scope this endpoint needs.",
  "status": 403,
  "code": "INSUFFICIENT_SCOPE",
  "request_id": "6f1c9e2a-…"
}

• code is stable: branch on it, not on title, which can be reworded.

• type is the page that explains the error. Open it in a browser.

• request_id identifies your request in our logs. Quote it when you contact us.

• An invalid parameter adds errors, one entry per parameter:

  "errors": [{ "detail": "Invalid option: expected one of …", "parameter": "status" }]

Codes

Status	Code	What to do
400	INVALID_REQUEST	Fix the parameter named in errors.
400	INVALID_CURSOR	Start again from the first page.
401	INVALID_TOKEN	Send a valid key or token, or refresh it.
403	INSUFFICIENT_SCOPE	Ask the member for the missing scope.
404	NOT_FOUND	Check the id, or the path.
422	SMART_LIST_UNSUPPORTED	Skip smart lists’ titles for now.
429	RATE_LIMITED	Wait the seconds in Retry-After.
503	UNAVAILABLE	Retry after the delay in Retry-After.
500	SERVER_ERROR	Retry later; tell us the request_id if it lasts.

A status the table does not list comes with type: "about:blank": its meaning is the HTTP status itself.