# Errors & status codes

> HTTP status codes returned by the Dailybot public API, machine-readable error codes, and how to recover.

Language: en
Canonical: https://www.dailybot.com/developers/errors
Markdown: send header `Accept: text/markdown` on any URL to receive Markdown instead of HTML.
Last Updated: 2026-07-10

---

The Dailybot API returns standard HTTP status codes on every response. Successful responses fall in the 2xx range; client errors in 4xx; server errors in 5xx. Every error body follows the same shape: a top-level `detail` string, a machine-readable `code`, and optional per-field validation errors under `errors`.

<h2 id="envelope">Error response envelope</h2>

Every non-2xx response is a JSON object with at minimum a `detail` and `code` field. Validation errors (400 responses on write endpoints) additionally include a per-field `errors` map. Rate limits (429) return a `Retry-After` header alongside the JSON body.

```json
{
  "detail": "Human-readable explanation",
  "code": "machine_readable_code"
}
```

Some errors include additional fields:
- `upgrade_url` — present on `plan_upgrade_required` responses, linking directly to the billing upgrade page
- `Retry-After` header — present on `429` responses, indicating seconds until the limit resets

> **Always dispatch on `code`, not `detail`.** The `detail` string is for humans; it may change. The `code` values are frozen — see [Machine-readable error codes](#machine-codes) below.

<h2 id="status-codes">Status codes returned by the public API</h2>

| Status | When you get it | How to recover |
|--------|-----------------|----------------|
| 200 OK | Successful GET, PATCH, or a POST that returns the resource. | Nothing to do — success. |
| 201 Created | Successful POST that creates a new resource. | The resource is in the response body; note the `uuid`. |
| 202 Accepted | Request was accepted for async processing (send-message, send-email, workflow trigger). | Poll or subscribe to a webhook to know when it completes. |
| 204 No Content | Successful DELETE or PATCH where no body is returned. | No body to parse; success. |
| 400 Bad Request | Validation error. The `errors` field contains per-field messages. Check `code` for specifics. | Fix the payload and retry. Never retry blindly. |
| 401 Unauthorized | Missing, expired, or invalid credential. | Confirm your API key or refresh your CLI Bearer session with `dailybot login`. |
| 403 Forbidden | Credential is valid but the caller lacks permission. Plan/auth 403s carry a stable `code` — see [machine codes](#machine-codes). | Check the `code` field and the [auth method matrix](/developers/authentication#parity-matrix). |
| 404 Not Found | Resource does not exist, or the caller cannot see it in this organization. | Verify the UUID and the scope of the credential. |
| 409 Conflict | The write conflicts with the current state (e.g. transitioning a form response to an invalid workflow state). | Re-read the resource, choose the correct next state, retry. |
| 422 Unprocessable Entity | The payload is syntactically valid but semantically invalid. | Read `detail` — the message identifies the offending field. |
| 429 Too Many Requests | Rate limit exceeded. | Respect the `Retry-After` header. See [/developers/rate-limits](/developers/rate-limits). |
| 500 Internal Server Error | Unexpected error on the Dailybot side. | Retry with exponential backoff. If it persists, contact support. |
| 502 / 503 / 504 | Upstream outage or maintenance window. | Retry with exponential backoff. |

<h2 id="retry-policy">Retry policy</h2>

Retry only on 429, 502, 503, 504, and idempotent 5xx. Never retry a 4xx blindly — the error is on your side. For 429, honor `Retry-After`; for 5xx, use exponential backoff (start at 250 ms, cap at 30 s, add jitter).

<h2 id="machine-codes">Machine-readable error codes</h2>

Every plan-gate, capability-gate, and rate-limit response carries a stable `code` field alongside the human-readable `detail`. Integrations should dispatch on `code`, never parse the prose.

> **Stability guarantee:** The `code` values listed here are **frozen** — existing values will never change meaning or be reused. New codes may be added in future API updates, but none of the codes below will ever change.

### Auth & plan gate codes

| `code` | HTTP | When you get it |
|--------|------|-----------------|
| `invalid_credentials` | 403 | Credentials supplied but don't resolve to a valid key or token |
| `api_key_owner_inactive` | 403 | The API key's owner user is deactivated |
| `plan_free_api_keys_forbidden` | 403 | The API key's organization is on a free plan |
| `plan_missing_core_api_integrations` | 403 | The org's plan doesn't include API access |
| `plan_upgrade_required` | 403 | Free-plan CLI Bearer token hit a non-allowlisted endpoint |
| `free_plan_daily_limit_exceeded` | 429 | Free-plan daily rate limit reached for this endpoint |
| `org_admin_required` | 403 | The action requires organization admin role |
| `member_in_scope_required` | 403 | Target user is not in the same organization |

### API key management codes

| `code` | HTTP | When you get it |
|--------|------|-----------------|
| `agent_key_admin_only` | 400 | Non-admin tried to create an agent key |
| `target_user_inactive` | 400 | Target user for key creation is deactivated |
| `target_user_not_found` | 400 | Target user UUID not found in the organization |

### Messaging codes

| `code` | HTTP | When you get it |
|--------|------|-----------------|
| `send_as_user_conflict` | 400 | `send_as_user` combined with `bot_username`, `bot_icon_url`, or `bot_icon_emoji` |
| `send_as_user_invalid_uuid` | 400 | Invalid UUID format in `send_as_user` |
| `send_as_user_not_found` | 400 | User not found, inactive, or in a different org for `send_as_user` |
| `cli_send_message_target_not_allowed` | 403 | CLI caller tried to send a message to an out-of-scope target |

### Filter & query codes

| `code` | HTTP | When you get it |
|--------|------|-----------------|
| `search_query_too_long` | 400 | `?search=` exceeds 256 characters. Applies uniformly to `/v1/forms/`, `/v1/checkins/`, `/v1/forms/{uuid}/responses/`, `/v1/checkins/{uuid}/responses/`, `/v1/kudos/`, `/v1/workflows/`, `/v1/users/`. |
| `invalid_date_range` | 400 | `?start_date` or `?end_date` is not a valid `YYYY-MM-DD` date, or `start_date > end_date`. Applies to every endpoint accepting `start_date` / `end_date`. |
| `invalid_user_identifier` | 400 | `?user=` is not a valid UUID. Use the user's UUID from `GET /v1/users/`. Applies to `/v1/checkins/{uuid}/responses/` and `/v1/forms/{uuid}/responses/`. |
| `not_valid_kudos_filter` | 400 | **Deprecated alias** — use `invalid_kudos_filter`. |
| `invalid_kudos_filter` | 400 | `?filter=` is not one of `kudos_received` / `kudos_given` (case-insensitive). Applies to `/v1/kudos/` and `/v1/kudos/organization/`. |
| `invalid_sender_uuid` | 400 | `?sender_uuid=` is not a valid UUID. Applies to `/v1/kudos/` and `/v1/kudos/organization/`. |
| `invalid_receiver_uuid` | 400 | `?receiver_uuid=` is not a valid UUID. Applies to `/v1/kudos/` and `/v1/kudos/organization/`. |
| `invalid_workflow_state` | 400 | `?state=` is not a valid workflow state for the form. Applies to `/v1/forms/{uuid}/responses/`. |
| `form_response_view_all_forbidden` | 403 | Member used `?all=true` on a form they are not allowed to view all responses for. |

> **JSON error responses:** Every `/v1/**` error response is guaranteed to be `application/json` — the API never returns HTML error pages for client-input validation failures.

### Authoring codes (forms & check-ins)

| `code` | HTTP | When you get it |
|--------|------|-----------------|
| `unknown_field` | 400 | Request body contains an unrecognized key on config endpoints |
| `questions_required` | 400 | Create called without at least one question |
| `short_question_required` | 400 | Question missing `short_question` without `generate_short_question` |
| `checkin_requires_participant` | 400 | Check-in create/config with zero participants |
| `anonymous_irreversible` | 400 | Attempt to disable anonymity on an anonymous check-in |
| `report_channel_not_found` | 400 | `report_channels` contains an ID not returned by `GET /v1/report-channels/` |
| `too_many_report_channels` | 400 | More than 3 report channels provided |
| `question_uuids_incomplete` | 400 | Reorder request missing one or more question UUIDs |

<h3 id="admin-only-endpoints">Admin-only endpoints</h3>

Non-admin members receive `403` with `code: "org_admin_required"` on these endpoints:

| Endpoint | Methods |
|----------|---------|
| `/v1/kudos/organization/` | GET |
| `/v1/webhook-subscription/` | POST, DELETE |
| `/v1/webhook-subscription/sample/` | POST |
| `/v1/open-conversation/` | POST |
| `/v1/teams/{uuid}/members/{uuid}/` | GET, PUT, PATCH, DELETE |
| `/v1/teams/{uuid}/invite/` | POST |
| `/v1/followups/` | POST (create only) |

---

## Developer portal navigation

**Getting Started**

- [Overview](/developers)
- [Quick start](/developers/getting-started)
- [Authentication](/developers/authentication)

**API Reference**

- [API Overview](/developers/api)
- [Users](/developers/api/users)
- [Organization](/developers/api/organization)
- [Teams](/developers/api/teams)
- [Invitations](/developers/api/invitations)
- [Check-ins](/developers/api/check-ins)
- [Forms](/developers/api/forms)
- [Report channels](/developers/api/report-channels)
- [Templates](/developers/api/templates)
- [Kudos](/developers/api/kudos)
- [Mood tracking](/developers/api/mood)
- [Important dates](/developers/api/important-dates)
- [Messaging](/developers/api/messaging)
- [Automations](/developers/api/workflows)
- [Webhooks](/developers/api/webhooks)
- [Commands platform](/developers/api/commands-platform)
- [Agents](/developers/api/agents)
- [OAuth2](/developers/api/oauth2)
- [Integrations](/developers/api/integrations)
- [CLI](/developers/api/cli)

**API guides**

- [Errors & Status Codes](/developers/errors) (this page)
- [Rate Limits](/developers/rate-limits)
- [Conventions](/developers/conventions)
- [API Changelog](/developers/api-changelog)
- [Recipes](/developers/recipes)

**Developer Features**

- [Custom commands](/developers/custom-commands)
- [Serverless commands](/developers/serverless)
- [Webhooks & events](/developers/webhooks)
- [Automation API trigger](/developers/workflow-trigger)
- [Activity API](/developers/activity-api)

**CLI**

- [Overview](/developers/cli)
- [Authentication](/developers/cli-authentication)
- [Command reference](/developers/cli-reference)
- [CI/CD recipes](/developers/cli-ci-cd)
- [Configuration](/developers/cli-configuration)
- [Troubleshooting](/developers/cli-troubleshooting)

**Agent Skill**

- [Overview](/developers/agent-skill)
- [Skills catalog](/skills)

---

## Site navigation

**Product:**
- [Home](/)
- [Product](/product)
- [Pricing](/pricing)
- [Enterprise](/enterprise)
- [Integrations](/integrations)
- [Templates](/templates)

**Resources:**
- [Blog](/blog)
- [Academy](/academy)
- [Changelog](/changelog)
- [Help Center](/help)
- [Developers](/developers)
- [Agents](/agents)

**Company:**
- [About](/about)
- [Careers](/careers)
- [Security](/security)
- [Contact Sales](/demo)

**Connect:**
- [LinkedIn](https://www.linkedin.com/company/dailybot/)
- [X/Twitter](https://twitter.com/dailybot)
- [GitHub](https://github.com/Dailybot-Inc)
- [YouTube](https://www.youtube.com/channel/UC3uM9V52vwX7e3vQpCc4qvA)