Skip to content
Foliosodev
Sign in Get started
Menu
On this page

REST API

Errors

The API always answers in JSON, including errors and unknown addresses. Every error body has a message, and validation errors add an errors object naming each field.

Status codes

Status Meaning What to do
200 OK The request worked.
201 Created A page, image or snapshot was created.
204 No Content A page was moved to the recycle bin. The body is empty.
308 Permanent Redirect Your organisation's address has changed. Update your base address. See 308: organisation has moved.
401 Unauthorized The token is missing, wrong, revoked or expired. Check the Authorization header, or create a new token.
403 Forbidden The token is valid, but this request isn't allowed. Read the message. See 403: not allowed.
404 Not Found The page, space, group or organisation doesn't exist, isn't in this token's organisation, or the endpoint doesn't exist. Check the slug, the id and the base address.
405 Method Not Allowed The endpoint exists but not with this method. Check the method, for example PATCH rather than PUT.
409 Conflict The page was restored from a snapshot, or its content was replaced through the API, since you read it. Read the page again and reapply your change. See Pages.
413 Content Too Large An uploaded image has too many pixels, or is still too large once converted. Upload a smaller image. See Images.
422 Unprocessable Content The request body or a parameter failed validation (an uploaded file that isn't a supported image is one), Markdown holds a malformed Folioso extension, or you asked for a page as Markdown that can't be written as Markdown without loss. Fix the fields listed in errors. See Folioso Markdown extensions and Content formats.
429 Too Many Requests You've gone over a rate limit. Wait for the number of seconds in Retry-After. See Authentication and limits.
500 Internal Server Error Something went wrong on Folioso's side. Try again later.

Error bodies

Most errors look like this:

json
{
  "message": "Unauthenticated."
}

403: not allowed

A 403 means the token was accepted but this request isn't allowed. The message says why:

Message Cause
Invalid ability provided. A read-only token called a write endpoint.
Your plan does not include this feature. The organisation's plan doesn't include API access.
You are no longer a member of this organisation. You've left or been removed from the organisation.
Your account in this organisation is suspended. Contact an administrator. Your membership is suspended.
This account must enrol in two-factor authentication before its API tokens can be used. You need to set up two-factor authentication.
This action is unauthorized. Your role doesn't allow this, for example creating a page in a space where you're a viewer, deleting a page you didn't write, moving or tagging a page that's only shared with you, or reading a private page in your recycle bin.

422: validation errors

json
{
  "message": "The title field is required. (and 1 more error)",
  "errors": {
    "title": ["The title field is required."],
    "space": ["The space field is required."]
  }
}

Each key in errors is a field name, and each value lists what's wrong with it.

404: not found

A 404 is the same whether something doesn't exist or belongs to another organisation, so a token can't be used to discover what exists elsewhere. A space you can't see, such as a private space you have no role in or a colleague's personal space, answers the same 404 as a space that doesn't exist. When you create or move a page, the message says which part wasn't found:

json
{
  "message": "No such group in that space."
}

308: organisation has moved

When an organisation changes its address, Folioso redirects requests from the old address for 30 days. Requests made with a token from that organisation get a 308 with the new address in the Location header and in the body:

json
{
  "message": "This organisation now lives at https://acme-labs.folioso.dev. Update your base URL.",
  "movedTo": "https://acme-labs.folioso.dev/api/v1/pages?space=engineering"
}

A 308 keeps the method and body, so a client that follows redirects repeats a POST or PATCH correctly. Not every client follows redirects automatically, so update your base address as soon as you see one. After 30 days, the old address returns 404.

Retrying safely

  • 429 and 5xx: wait and retry. For 429, honour Retry-After.
  • 409: read the page again before retrying. Sending the same body again would undo the restore.
  • 401, 403, 404 and 422: retrying won't help until you change the request or the token.
  • POST /pages isn't idempotent. If a create times out, list the space's pages before retrying, or you may create the page twice.
  • POST /images isn't idempotent either, but retrying is harmless: an upload no page uses is deleted after its expiresAt. See Images.