Errors, retries, and limits

Error envelope

Every non-2xx response uses the same shape:

{
  "error": {
    "type": "invalid_request",
    "code": "lead_not_in_campaign",
    "message": "The following lead IDs do not belong to this campaign: d6a8..., e7b9..."
  }
}

• type is the category — coarse-grained, useful for branching error-handling logic.
• code is the specific reason — programmatic, stable across releases (we won't rename a code in a non-breaking way).
• message is human-readable — show it in logs, don't parse it.

HTTP status codes

422 — schema validation (different envelope)

FastAPI emits HTTP 422 with a different body shape when a request fails schema validation — e.g. you POST /v1/campaigns/{id}/batches without the required message_body field, or pass the wrong type for lead_ids. The body looks like:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "message_body"],
      "msg": "Field required",
      "input": { ... }
    }
  ]
}

This is not the { "error": { "type": "...", "code": "...", "message": "..." } } envelope you'll see for every other 4xx. If your client parses error.code and crashes on missing key, branch on status === 422 first. The 422 will never be retried-into-success — it's a client-side schema bug, fix the payload.

Specific error codes you'll encounter

POST /v1/campaigns/{id}/batches

Anywhere

Retry guidance

Idempotency: not supported in v1

POST /v1/campaigns/{id}/batches is not idempotent. Retrying the same request body may create a duplicate batch.

Stripe-style Idempotency-Key is on the v1.1 roadmap.

Recommended retry policy on transient failures

Exponential backoff with jitter, max 3 attempts:

import time, random

def with_retries(call, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            resp = call()
            if resp.status_code < 500 and resp.status_code != 408:
                return resp
        except (ConnectionError, Timeout):
            pass
        if attempt < max_attempts - 1:
            time.sleep((2 ** attempt) + random.random())
    raise Exception("retries exhausted")

Rate limits

Not enforced in v1. We may add a per-key token bucket before onboarding a second customer; if so, the response will be 429 with a Retry-After header. Build your retry logic to handle it now — it's cheap insurance.

Pagination

Cursor-based on (created_at, id). Responses include:

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0w..."
}

Pass the next_cursor verbatim as starting_after on the next call. The cursor is opaque — don't parse it. We may change the format without notice.

has_more is false on the final page; next_cursor will be null.

limit defaults to 50, max 200. Larger pages are not currently supported.

Versioning

The API is versioned via URL prefix (/v1). Within /v1 we make only additive changes:

• New optional request fields
• New response fields
• New error codes
• New event types

We will not:

• Remove or rename fields
• Tighten validation in a way that breaks previously-accepted requests
• Change response field types

If we need to make a breaking change, it ships under /v2 and /v1 continues operating in parallel for a deprecation window.

Build your receiver to ignore unknown fields — that's the contract that keeps additive evolution non-breaking.