Errors
The error envelope, the status codes you will hit and what to do about each.
Every error is JSON with a detail string. Validation errors from the framework carry a detail array instead; treat both as "read detail".
JSON
{ "detail": "window_start must be HH:MM (24h), e.g. 08:00" }| Status | Meaning | Do |
|---|---|---|
400 | The request is malformed or a rule was broken | Read detail, fix the field |
401 | No or invalid key | Mint a key, send it as a bearer token |
402 | The plan does not include this | The detail carries an upgrade URL |
403 | Key lacks the permission or scope | Ask an owner for the right, or a scope on the OAuth grant |
404 | Not yours or does not exist | Check the id; workspaces are isolated |
409 | Precondition | e.g. stop a campaign before deleting it, launch blockers, built-in status cannot be removed |
422 | Body failed validation | detail lists the fields |
429 | Daily allowance or burst limit | Wait for Retry-After, then retry |
5xx | Our side | Retry with backoff; the request was not applied |
Launch blockers
POST /api/v1/campaigns/{id}/launch refuses with 409 while the campaign has no complete email, no active sender with capacity or no queued lead. GET /api/v1/campaigns/{id} returns the same list as launch_blockers, so an agent can resolve them before trying.
Idempotency
Creating campaigns, lists and exports is not idempotent; enrolling leads is (duplicates are skipped and reported as duplicates_skipped). Webhook deliveries are replay-safe through X-Argorant-Delivery.