Errors - FirstSales Developer

Every public API error uses a stable envelope.

{
  "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.

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.