Error reference

Every API error is JSON with a stable machine-readable code, a human-readable message, and a referenceId you can give support. Validation errors add a details object keyed by field. Codes are append-only — build against them safely.

{
  "error": {
    "code": "WAVEBAND_VALIDATION",
    "message": "The request failed validation.",
    "details": { "budgetUsdMinor": "must be a positive integer" },
    "referenceId": "8afaaee8-e7ab-4702-9802-881b52e02faf"
  }
}

Retry guidance

429 — back off and retry after the Retry-After header.
409 WAVEBAND_SYNC_PENDING — the entity has an in-flight change; retry once its sync settles (watch sync.succeeded.v1 webhooks).
502 WAVEBAND_PROVISIONING_FAILED — already queued for retry on our side; do not resubmit the same change.
5xx on a POST — retry with the same Idempotency-Key; you will never double-create.

All error codes

HTTP	Code	Default message
400	`WAVEBAND_VALIDATION`	The request failed validation.
400	`WAVEBAND_BUDGET_BELOW_DELIVERED`	Budget cannot be set below the amount already delivered.
400	`WAVEBAND_BUDGET_BELOW_MINIMUM`	Daily budget is below the platform minimum of $1.00.
400	`WAVEBAND_BUDGET_CAP_REACHED`	This change would exceed the account spend cap. Contact support to raise it.
400	`WAVEBAND_TARGETING_INVALID`	The targeting expression is invalid.
400	`WAVEBAND_TARGETING_EMPTY_REACH`	This targeting combination has no available reach.
400	`WAVEBAND_CREATIVE_INVALID`	The creative failed validation for its channel.
400	`WAVEBAND_CREATIVE_CHANNEL_MISMATCH`	This creative type cannot be attached to a line item of this channel.
400	`WAVEBAND_ACTIVATION_NO_CREATIVES`	A line item cannot go live without at least one attached creative.
400	`WAVEBAND_SEGMENT_TOO_SMALL`	This audience is below the minimum size required for activation.
401	`WAVEBAND_UNAUTHORIZED`	Authentication is required.
402	`WAVEBAND_ACTIVATION_BLOCKED_BILLING`	Activation is blocked until the outstanding balance is settled.
402	`WAVEBAND_PAYMENT_FAILED`	The payment method was declined. Update it to continue.
402	`WAVEBAND_CREDIT_LIMIT_EXCEEDED`	This account has reached its credit limit.
403	`WAVEBAND_FORBIDDEN`	You do not have access to this resource.
403	`WAVEBAND_ACTIVATION_RISK_HOLD`	Activation requires review for new accounts at this spend level.
403	`WAVEBAND_FEATURE_NOT_ENABLED`	This feature is not enabled for your plan. Contact support to enable it.
404	`WAVEBAND_NOT_FOUND`	The requested resource was not found.
409	`WAVEBAND_IDEMPOTENCY_CONFLICT`	A different request with this idempotency key was already processed.
409	`WAVEBAND_SYNC_PENDING`	This entity has a pending sync. Retry once it settles.
409	`WAVEBAND_CREATIVE_TRANSCODING`	The creative is still transcoding. It can be attached once processing completes.
409	`WAVEBAND_CREATIVE_REJECTED`	The creative was rejected by an exchange review. See the approval status for details.
429	`WAVEBAND_RATE_LIMITED`	Rate limit exceeded. Retry after the indicated delay.
500	`WAVEBAND_INTERNAL`	Something went wrong on our side. Our team has been notified.
502	`WAVEBAND_PROVISIONING_FAILED`	Your change could not be applied to the delivery infrastructure. It has been queued for retry; support has the reference id.