Errors

Every error response follows the same envelope:

{
  "code": "...",
  "type": "https://docs.ampout.dev/errors/<code>",
  "message": "...",
  "details": { ... }
}

code is the only thing your client should branch on — message is human-readable and may change. The HTTP status is determined by the code; both are documented below.

Generic

Code	Status	Fires when
unauthorized	401	Missing, malformed, or revoked API key.
not_found	404	Generic fallback for resources without a dedicated code.
validation_failed	422	Model validation failed. message carries the validator’s full message.
unprocessable	422	Request was syntactically valid but couldn’t be processed (e.g., business-rule violation).
bad_request	400	Malformed request.
rate_limited	429	Exceeded the per-key (60/min) or per-IP signup throttle. Includes Retry-After.

Resource-not-found (one per resource)

These all return 404. They’re semantically equivalent to not_found but emit distinct codes so your client can branch precisely.

Code	Resource
campaign_not_found	Campaign
contact_not_found	Contact
contact_import_not_found	ContactImport
outreach_not_found	Outreach
smtp_credential_not_found	SmtpCredential
api_key_not_found	ApiKey
webhook_not_found	Webhook
plan_not_found	Plan

Campaign workflow

Code	Status	Fires when
no_pending_enrollments	422	POST /campaigns/:id/dispatch and there’s nothing to dispatch.
campaign_not_active	422	POST /campaigns/:id/pause on a non-active campaign.
campaign_not_paused	422	POST /campaigns/:id/resume on a non-paused campaign.
contact_already_enrolled	422	POST /campaigns/:id/enroll_contact and the contact already has an enrollment.
no_emails_provided	422	POST /campaigns/:id/test_send without any emails.
no_contacts_provided	422	POST /contact_imports without any contacts.

Billing

Code	Status	Fires when
plan_limit_reached	402	Account has reached its plan’s monthly send limit. details includes current_period_sends, monthly_limit, plan_slug.
plan_required	402	(Reserved for paid-only features in the future.)
feature_not_in_plan	402	(Reserved for paid-only features in the future.)
plan_not_purchasable	422	POST /billing/checkout for a free or private plan.
no_stripe_customer	422	POST /billing/portal or /checkout and the account has no Stripe customer (signed up before Stripe was wired).

API key management

Code	Status	Fires when
cannot_revoke_last_key	422	DELETE /api_keys/:id would leave the account with zero active keys.

Webhooks (inbound)

Code	Status	Fires when
invalid_signature	401	POST /webhooks/stripe HMAC signature verification fails. (Inbound only — your outbound webhook receiver is responsible for its own signature checks.)

Idempotency

Code	Status	Fires when
idempotency_conflict	409	Same Idempotency-Key reused with a different request body.

Example responses

404 (resource not found)

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "code": "campaign_not_found",
  "type": "https://docs.ampout.dev/errors/campaign_not_found",
  "message": "Campaign not found"
}

422 (validation failed) — note the dynamic message

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "code": "validation_failed",
  "type": "https://docs.ampout.dev/errors/validation_failed",
  "message": "Name can't be blank, Min wait seconds must be greater than or equal to 0"
}

402 (plan limit reached)

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "code": "plan_limit_reached",
  "type": "https://docs.ampout.dev/errors/plan_limit_reached",
  "message": "Plan send limit reached for the current period",
  "details": {
    "current_period_sends": 5000,
    "monthly_limit": 5000,
    "plan_slug": "hobby"
  }
}

429 (rate limited)

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "code": "rate_limited",
  "type": "https://docs.ampout.dev/errors/rate_limited",
  "message": "Too many requests. Slow down and retry after the period resets.",
  "details": { "limit": 60, "period": 60 }
}