> ## Documentation Index
> Fetch the complete documentation index at: https://developer.firstsales.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Stable error envelope for Developer API clients.

Every public API error uses a stable envelope.

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "API key scope insufficient for action: campaigns:write",
    "requestId": "req_123",
    "details": {}
  }
}
```

## Common codes

| Code | Meaning |
| - | - |
| `missing_auth` | No bearer key was provided. |
| `invalid_api_key` | The key is invalid, revoked, or no longer active. |
| `insufficient_scope` | The key does not grant the requested action. |
| `workspace_required` | A workspace-scoped resource was called without a workspace target. |
| `not_found` | The resource was not found or is not visible to this key. |
| `rate_limited` | The key or organization exceeded a rate limit. |
| `idempotency_key_required` | `400`. The route requires an `Idempotency-Key` header and none was sent. |
| `idempotency_key_reused` | `409`. The key was already used for a different method, route, or body. |
| `idempotency_request_in_progress` | `409`. The first request with this key is still running. Retry the same request later. |
| `unsupported_operation` | The operation is not part of the public Developer API. |
| `session_required` | `403`. The app route accepts browser sessions only. Use the matching `/api/v1` route. |
| `bad_request` | `400`. The body failed validation. |
| `workflow_node_missing` | `409`. The campaign graph has no node to hold the lists or senders. |
| `workflow_changed` | `409`. The campaign graph changed during the update. Read it again and retry. |
| `list_not_in_workspace` | `422`. A list id is not in this workspace. |
| `connector_not_eligible` | `422`. A connector is not a verified email sender in this workspace. |
| `blocked_domain` | `422`. A recipient is on a blocked domain. Also the skip reason for sequence sends. |
| `recipient_suppressed` | `422`. A recipient is suppressed. |
| `sender_not_authenticated` | `422`. The sending mailbox is not authenticated. |
| `active_sequence` | `409`. The contact is in an active sequence. |
| `already_sending` | `409`. The email is already being sent and cannot change. |
| `already_cancelled` | `409`. The email was already cancelled. |
| `scheduled_at_must_be_future` | `400`. The scheduled time is in the past. |
| `connector_exists` | `409`. The workspace already has this connector. |
| `cal_com_key_invalid` | `400`. Cal.com rejected the key. |
| `cal_com_booking_url_mismatch` | `400`. The booking URL does not belong to the Cal.com account. |
| `cal_com_event_not_owned` | `400`. The event type does not belong to the Cal.com account. |
| `cal_com_unavailable` | Cal.com returned an error. The status follows Cal.com. |
| `cal_com_webhook_failed` | `502`. The booking webhook could not be registered. |
| `cal_com_not_configured` | `503`. Cal.com is not configured on this deployment. |

Codes for the headless routes are listed on
[Headless operations](/docs/headless-operations).

## Request IDs

Capture `requestId` when asking support to investigate a failed integration. Request logs in the FirstSales app can also be filtered by request ID.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.