Errors Reference

All API errors return JSON with an error field describing what went wrong.

{
  "error": "name is required"
}

HTTP Status Codes

Code	Meaning	When it occurs
200	OK	Successful GET or PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Invalid input, missing required fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid key but insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Daily creation limit exceeded
500	Internal Server Error	Server-side bug

---

Error Messages

Authentication Errors

Error	Status	Cause
"Unauthorized"	401	Bearer token missing, malformed, or not found
"Forbidden"	403	Valid token but doesn't match the workspace owner

Channel Errors

Error	Status	Cause
"name is required"	400	name field missing from request body
"workspace_id is required"	400	workspace_id field missing
"Channel not found"	404	Channel ID doesn't exist
"Workspace not found"	404	workspace_id doesn't exist
"Daily channel limit reached"	429	50 channels created today

Card Errors

Error	Status	Cause
"blocks are required"	400	blocks array missing or not an array
"Card not found"	404	Card ID doesn't exist in this channel
"Daily card limit reached"	429	200 cards created today

Workspace Errors

Error	Status	Cause
"Workspace limit reached"	400	User already has 3 workspaces
"Cannot delete last workspace"	400	Attempting to delete the only workspace
"Workspace not found"	404	Workspace ID doesn't exist
"custom_slug already taken"	400	Another workspace uses that slug

Attribute Errors

Error	Status	Cause
"Cannot use reserved key"	400	Attempted to set created_at or updated_at

---

Troubleshooting

Getting 401 on every request

1. Check you're using Authorization: Bearer ofd_... (not Token, APIKey, etc.)
2. Verify the key hasn't been regenerated — regenerating creates a new key and revokes the old one
3. If using Secure Mode, ensure you're sending the workspace owner's key

Getting 403 but token is correct

• You may be sending a key from a different user/workspace
• The workspace you're targeting belongs to a different account

Getting 429 unexpectedly

• Daily limits reset at midnight UTC, not midnight local time
• Check usage in Dashboard → Sidebar (shows today's channel/card counts)
• Both channel and card creation counts against the per-resource daily limits

Channel created but not visible

• Check the channel's visibility setting — "private" channels require authentication
• If in a "protected" workspace, the visitor must unlock via password first

Webhook not firing

1. Check webhook_url is set on the channel
2. Check the channel mode is "interactive" (button clicks won't fire in "view" mode)
3. Check Channel → Logs for delivery attempts and response codes
4. Ensure your endpoint returns 2xx — non-2xx logs as "failed"
5. Ensure your endpoint is publicly accessible (no localhost URLs)