Skip to main content

​
Introduction

The API uses a consistent error format across all endpoints. This page explains how errors are returned and how to interpret error responses.

​
Error Response Format

All error responses follow a shared structure: 
{
  "error": "Human-readable error message",
  "code": "Optional machine-readable error code"
}

​
Fields

FieldDescription
errorA descriptive message explaining what went wrong.
code(Optional) A short error identifier you can use for programmatic handling.

​
HTTP Status Codes

The Public API uses standard HTTP status codes to indicate success or failure.

​
400 – Bad Request

Returned when:
  • A parameter is invalid (e.g., malformed ObjectId).
  • A required field is missing.
  • A resource does not exist (e.g., channel not found).
Example: 
{
  "error": "Channel not found",
  "code": "INVALID"
}

​
403 – Forbidden

Returned when the integration does not have the required permissions. Examples: Sending chat messages without permission: 
{
  "error": "You are not allowed to send messages to this channel",
  "code": "FORBIDDEN"
}
Accessing boards or tables without permissions: 
{
  "error": "You are not allowed to access boards",
  "code": "FORBIDDEN"
}

​
404 – Not Found

Some operations may return a 400 with a specific message instead of 404. However, if an endpoint returns 404, it indicates the resource doesn’t exist or cannot be accessed.

​
429 – Rate Limit Exceeded

Returned when the integration exceeds the defined rate limits. Rate limits vary by endpoint:
  • Chat Messaging: 100 requests/minute
  • Board Operations: 30–50 requests/minute depending on the endpoint
Example: 
{
  "error": "Too Many Requests"
}

​
Common Error Scenarios

​
1. Invalid ObjectId Format

Object IDs must be 24-character hex strings. Occurs when:
  • Passing an invalid channelId, boardId, tableId, or rowId.
API response example: 
{
  "error": "Invalid parameter: boardId"
}

​
2. Missing Required Fields

Example from the Chat API: If message is omitted: 
{
  "error": "message is a required field"
}

​
3. Permission Errors

Occurs when the integration is not granted access to the resource. Examples:
  • Integration not added to a text channel
  • Missing ACCESS_CHANNELS
  • Missing ACCESS_BOARDS
These return 403 errors.

​
4. Resource Not Found

Occurs when the resource does not exist in the workspace or the integration does not have access. Example: 
{
  "error": "Channel not found",
  "code": "INVALID"
}

​
5. Invalid Column Definitions (Board API)

When creating a table row, only certain column types are supported. If an unsupported column is included, it is ignored. If no valid columns are included, the row will still be created without column values.

​
Summary

  • Errors follow a consistent { error, code } structure.
  • Common status codes include 400, 403, and 429.
  • Permission issues return 403.
  • Invalid or missing fields return 400.
  • Rate limits vary by endpoint.