Error Codes - ColdSend API

The ColdSend API uses standard HTTP status codes and returns structured error responses.

Always check the HTTP status code first, then parse the detail field for specific error information.

HTTP Status Codes

Status Code	Description
`200 OK`	Request succeeded
`201 Created`	Resource created
`204 No Content`	Succeeded with no body
`400 Bad Request`	Invalid request or validation error
`401 Unauthorized`	Missing or invalid API key
`402 Payment Required`	Not enough credits for a credit-spending operation
`403 Forbidden`	Insufficient scopes
`404 Not Found`	Resource doesn’t exist
`409 Conflict`	Resource already exists, or the contact cannot be emailed
`422 Unprocessable`	Validation error
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error
`503 Service Unavailable`	Temporarily unavailable

Error Response Format

All errors return a detail field: Simple error:

{
  "detail": "Error message describing issue"
}

Validation error:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "ensure this value has at least 8 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}

Multiple fields:

{
  "detail": [
    {
      "loc": ["body", "daily_limit_per_inbox"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

The detail field contains either a simple string or an array of validation failures with loc (field path), msg (human-readable), and type (error category).

Authentication Errors

Missing API Key

Status: 401 Unauthorized

{
  "detail": "API key required. Include your API key in X-API-Key header."
}

Fix: Include X-API-Key: cs_live_your_key in every request.

Invalid or Revoked Key

Status: 401 Unauthorized

{
  "detail": "Invalid or revoked API key"
}

Fix: Generate a new API key in the dashboard. Revoked keys cannot be restored.

Insufficient Permissions

Status: 403 Forbidden

{
  "detail": "Missing required scopes: campaigns:write",
  "error": "insufficient_scopes",
  "required": ["campaigns:write"],
  "granted": ["sender_accounts:read"]
}

Fix: Create a new API key with the required scopes. See API Key Scopes.

Validation Errors

Field Required

Status: 422 Unprocessable Entity (via FastAPI) or 400 Bad Request

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Value Constraint Violated

{
  "detail": [
    {
      "loc": ["body", "daily_limit_per_inbox"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

Common constraints:

Campaign name: 8-255 characters
Daily limit per inbox: 1-100
Variant distribution: must sum to 100%

Invalid Format

{
  "detail": [
    {
      "loc": ["body", "email_address"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Campaign Errors

Campaign Not Found

Status: 404 Not Found

{
  "detail": "Campaign 550e8400-e29b-41d4-a716-446655440000 not found"
}

Check:

Campaign ID is a valid UUID
Campaign belongs to your team
Campaign hasn’t been deleted

Campaign Not Modifiable

Status: 400 Bad Request

{
  "detail": "Can only update campaigns in DRAFT status"
}

Fix: Pause the campaign first via POST /api/public/v1/campaigns/{id}/pause, then make updates.

Missing Launch Requirements

When you set launch: true, the API validates and may return:

{
  "is_launch_ready": false,
  "missing_requirements": ["leads", "inboxes", "variants"]
}

Fix the missing items and retry. See Campaigns Overview.

Variant Distribution Mismatch

{
  "detail": "Variant distributions must sum to 100%, got 90%"
}

All distribution_percent values must sum to exactly 100.

Sender Account Errors

Inbox Already Exists

Status: 409 Conflict

{
  "detail": "Inbox already exists"
}

Fix: Use a different email address, or delete the existing inbox first.

Connection Failed

Status: 400 Bad Request

{
  "detail": "Failed to connect to your email provider. Please verify your credentials and app password settings."
}

Fix:

Verify SMTP/IMAP hostnames and ports match your provider’s config
Check credentials — use app-specific passwords, not main passwords
See Provider Configuration for recommended settings

Inbox In Use

Status: 400 Bad Request

{
  "detail": "Inbox is assigned to a campaign and cannot be deleted. Remove from campaigns first."
}

Fix: Remove the inbox from all campaigns it’s assigned to, then retry deletion.

Direct Email Errors

Returned by POST /api/public/v1/contacts/{contact_id}/send-email, the only public endpoint that spends credits. See Direct Email.

Insufficient Credits

Status: 402 Payment Required

{
  "detail": {
    "message": "Insufficient credits to send this email",
    "required": 1,
    "available": 0
  }
}

Nothing is sent and nothing is charged. The required and available counts let you decide whether to top up or skip. Fix: Add credits in the dashboard, then retry. A direct email costs 1 credit per send.

402 is new to the public API surface and currently only reachable from this endpoint. Every other public route is free of credit cost.

Suppressed Contact

Status: 409 Conflict

{
  "detail": {
    "message": "This contact cannot be emailed",
    "reason": "blocklist",
    "block_type": "DOMAIN",
    "blocked_value": "example.com",
    "email": "alice@example.com"
  }
}

reason is one of:

Reason	Meaning
`blocklist`	The address or its domain is on your team blocklist — `block_type` is `EMAIL` or `DOMAIN` and `blocked_value` names the entry
`unsubscribed`	The contact unsubscribed — `block_type` and `blocked_value` are `null`
`bounced`	A previous send to the contact hard-bounced — `block_type` and `blocked_value` are `null`

The suppression check runs before the credit is deducted, so a refused send costs nothing. Fix: This is a compliance control, not a transient failure — do not retry. Remove the address from the blocklist in the dashboard only if you are sure you may contact them.

GET /api/public/v1/contacts/{contact_id} returns contact.is_suppressed and contact.suppression_reason, so you can check before attempting a send and avoid the 409 entirely.

Sending Inbox Unavailable

Status: 404 Not Found when the inbox does not exist in your team, 400 Bad Request when it exists but cannot send (not ACTIVE, or has no sender address):

{
  "detail": "Inbox is not active"
}

Fix: List usable inboxes with GET /api/public/v1/sender-accounts?status=ACTIVE and pass one of the returned inbox_id values.

Inbox resolution for this endpoint is team-scoped, while GET /sender-accounts is workspace-scoped. An API key pinned to one workspace can therefore send from an inbox the sender-accounts list does not show. Prefer an inbox that appears in both.

Rate Limit Error

Status: 429 Too Many Requests

{
  "detail": "Rate limit exceeded. Retry after 60 seconds."
}

Fix: Implement exponential backoff. See Rate Limits.

Best Practices

Check status codes — Differentiate 4xx (client errors, fix the request) from 5xx (server errors, retry with backoff).
Implement retry logic — Retry on 429 and 5xx with exponential backoff. Don’t retry 4xx errors (except 409/422 with fixes).
Log errors — Include timestamps, request IDs, and context in your logs.
Display user-friendly messages — Convert technical errors into actionable guidance.
Use separate keys per integration — Makes debugging scope issues easier.

​HTTP Status Codes

​Error Response Format

​Authentication Errors

​Missing API Key

​Invalid or Revoked Key

​Insufficient Permissions

​Validation Errors

​Field Required

​Value Constraint Violated

​Invalid Format

​Campaign Errors

​Campaign Not Found

​Campaign Not Modifiable

​Missing Launch Requirements

​Variant Distribution Mismatch

​Sender Account Errors

​Inbox Already Exists

​Connection Failed

​Inbox In Use

​Direct Email Errors

​Insufficient Credits

​Suppressed Contact

​Sending Inbox Unavailable

​Rate Limit Error

​Best Practices

​Next Steps

Authentication

Rate Limits

HTTP Status Codes

Error Response Format

Authentication Errors

Missing API Key

Invalid or Revoked Key

Insufficient Permissions

Validation Errors

Field Required

Value Constraint Violated

Invalid Format

Campaign Errors

Campaign Not Found

Campaign Not Modifiable

Missing Launch Requirements

Variant Distribution Mismatch

Sender Account Errors

Inbox Already Exists

Connection Failed

Inbox In Use

Direct Email Errors

Insufficient Credits

Suppressed Contact

Sending Inbox Unavailable

Rate Limit Error

Best Practices

Next Steps