Campaign API Error Handling
Common errors when using the Campaign API and how to resolve them.
400 validation_error — Invalid Request Body
Cause: Missing required fields or invalid values.
Common issues:
• 'name' is required and must be 1-200 characters
• 'steps' array must have at least 1 step and at most 50
• 'mailboxIds' array must have at least 1 mailbox ID
• 'dailySendLimit' must be between 1 and 10,000
• Each step must have a unique 'stepIndex' (duplicates are rejected)
• 'endDate' must be in the future and after 'startDate'
Fix: Check the error response 'details' field for specific validation failures.
400 unusable_mailboxes — Mailbox Not Usable
Cause: One or more mailboxes are disconnected or have sending disabled.
Fix: Go to Settings > Mailboxes and reconnect the mailbox. Ensure 'Sending Enabled' is turned on.
400 invalid_status — Wrong Campaign Status
Cause: Attempting an action not allowed for the current status.
• Cannot update a running campaign — pause it first (POST /:id/pause)
• Cannot start a completed or errored campaign
• Cannot pause a draft or already-paused campaign
Fix: Check the campaign status with GET /api/v1/campaigns/:id first.
400 end_date_expired — End Date Has Passed
Cause: Trying to start a campaign whose end date is already in the past.
Fix: Update the end date (PATCH) or set it to null to remove it.
403 insufficient_scope — Missing API Key Scope
Cause: Your API key does not have the required scope.
• Creating/updating/starting/pausing: requires campaigns:write
• Reading campaign data: requires campaigns:read
• Enrolling prospects: requires enrollments:write
Fix: Create a new API key with the needed scopes in Settings > API Keys.
403 subscription_blocked — Subscription Issue
Cause: Your subscription is inactive, past due, or expired.
Fix: Visit Settings > Billing to update your payment method or renew.
404 not_found — Campaign Not Found
Cause: The campaign ID does not exist, belongs to a different workspace, or was deleted.
Fix: Verify the campaign ID. Use GET /api/v1/campaigns to list all campaigns.
409 conflict — Duplicate Data
Cause: Duplicate prospect enrollment (same prospect already enrolled in this campaign).
Fix: Check existing enrollments before enrolling. Use the Idempotency-Key header for safe retries.
429 Too Many Requests — Rate Limited
Cause: Exceeded 60 requests per minute.
Fix: Implement exponential backoff. Wait and retry after the rate limit window resets.
Idempotency Tips:
- Use the Idempotency-Key header on POST /api/v1/campaigns for safe retries
- Each unique key caches the response for 24 hours
- If your request times out, retry with the same key — you will get the cached result, not a duplicate campaign
- Generate keys using UUIDs (e.g., crypto.randomUUID())