Errors and conventions

This page covers the rules every Tylode API endpoint follows: how errors look, what each status code means, how big lists can get and how to handle dates. Knowing them saves you from most surprises when building an integration.

#Error format

When something fails, the API returns a non-2xx status code and a JSON body with the message and a fixed code:

{ "error": "Page not found.", "code": "page_not_found" }

error is written for people reading logs and can change at any time. It's in the language Accept-Language asks for, out of the 13 app languages (for example Accept-Language: de), in Spanish if you send no header, and in English if you ask for a language we don't have. code doesn't change: if your program needs to tell one error from another, use the status code and code, never the text. Plan limits and other messages from the database have code: "error" and only exist in Spanish.

const res = await fetch(url, { headers });
if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: res.statusText }));
  if (res.status === 429) {
    // wait for the next minute and retry
  }
  throw new Error(`Tylode API ${res.status}: ${error}`);
}

The OAuth token endpoint is the one exception: it uses the standard OAuth format (error plus error_description). See OAuth 2.0 apps.

#Status codes

A 401, 403 or 429 means nothing was done, so fixing the cause and repeating the request is always safe.

#Things you can't see look empty

The API acts as you and only returns what you can see in the app. For lists, that means things you don't have access to don't produce an error: they're just missing. If you pass the ID of a workspace you're not a member of, GET /pages?workspace_id=… returns { "data": [] } rather than 403 or 404.

If a list comes back empty when you expected results:

1. Call GET /workspaces and check that the workspace_id is one of yours.
2. Check that the item is visible to you in the app. Private boards, whiteboards and databases that haven't been shared with you don't appear.
3. For OAuth apps, remember that the user who authorized the app is the one whose access counts.

For single items (such as GET /pages/:id), something you can't see returns 404, exactly like something that doesn't exist.

#No pagination

List endpoints return everything in one response; there are no cursors or pages. A few endpoints have a fixed size instead:

Everything else (pages, boards, cards, events, rows, whiteboard items…) comes in full. For big workspaces, ask for less: filter calendar events with from and to, or use search instead of listing everything.

#No idempotency keys

The API doesn't support idempotency keys. Sending the same POST twice creates two pages, two cards or two messages.

• Retry GET requests freely.
• Retry any request that got 401, 403 or 429: nothing was done.
• Retry a DELETE without worrying: if it already happened, you get 404 and nothing else changes.
• Don't retry a POST blindly after a timeout or a network error. It may have worked. List first (for example, look for a card with that title) and create only if it's missing.
• For webhooks, which go the other way, use the delivery ID to spot duplicates. See Webhooks.

#Deleting: trash or permanent

DELETE endpoints do the same as deleting in the app:

• Anything with a trash goes to the trash and can be recovered from the app: pages (with their subpages), boards, whiteboards, presentations and My drive files.
• Everything else is deleted for good: cards, events, database rows, slides, and whiteboard and slide elements.

The response tells you which one happened:

{ "data": { "id": "c4f7a0d3-6b9e-4c2f-8a5d-1e4b7c0f3a96", "papelera": false } }

id is the ID of what you deleted, and papelera ("trash") is true if it went to the trash or false if it was deleted for good.

• If it doesn't exist, you can't see it, you aren't allowed to delete it, or it was already in the trash, you get 404 with code: "not_found_or_cannot_delete".
• If you can see a board or whiteboard but your role doesn't let you move it to the trash, you get 403 with the same code.
• OAuth apps need the resource's :delete scope, which is separate from :write. See Scopes.
• Chats, mail, notifications and search have nothing to delete through the API.

#Dates and time zones

• Every timestamp the API returns is ISO 8601 in UTC, like 2026-09-23T08:30:00+00:00. Convert to local time in your code.
• When you send a date (for example start_at for a calendar event, or from and to), include the offset or a Z: 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A time without an offset is read as UTC.
• In query strings, encode the + of an offset as %2B, or use Z to avoid the problem.

#CORS: call the API from a server

The API doesn't send CORS headers, so a browser won't let a page on another domain read its responses. That's on purpose: calling the API from the browser would mean putting a token that can do everything in code anyone can read.

• Call the API from your server, a serverless function or a script.
• To show something inside Tylode, build a plugin: it talks to the API through Tylode, without a token.
• For apps used by other people, use OAuth and keep the tokens on your server.

#Versioning

All endpoints live under /api/v1. New fields may be added to responses and new endpoints may appear, so write clients that ignore fields they don't recognize and don't depend on the order of keys in a JSON object. Webhook header names are stable.

#Related pages

• Authentication: tokens and rate limits.
• Developer platform: conventions and endpoint index.
• Troubleshooting: problems that aren't specific to the API.