Read the error envelope
{
"error": {
"code": "validation_error",
"message": "Missing required field(s).",
"details": {"missing": ["display_name"]}
}
}Handle 400/422 by correcting input; 401 by checking or rotating the key; 403 by using the correct permission level; 404 by checking the saved company ref; 409 by checking workflow state; 429 by backing off; and 503 by handling upstream unavailability. Inspect machine-readable error.code and optional error.details.
Rate limits and polling
The default quota is 120 requests/hour per source IP per endpoint. OTP sending also has a 10/minute limit, verification 20/minute, plus the resend cooldown. Use roughly 60-second polling intervals and exponential backoff; workflows behind one IP share each endpoint’s quota, and all MCP calls share the MCP endpoint quota. Honor Retry-After when present. Production configuration may change these limits.
Retry safely
Direct POST /brands supports Idempotency-Key: identical bodies reuse the original brand, changed bodies return 409 idempotency_conflict. Older keys without a stored request fingerprint return 409 legacy_idempotency_key and the saved brand_ref so you can resume that record. Retrying scan, generation or campaign creation after an ambiguous timeout can create duplicates. Save refs immediately; do not blindly retry these operations. Repeating campaign submission while it remains pending review is safe. Use the paginated brand and campaign lists to recover existing refs. Outbound partner webhooks are not available. New registrations also have a paginated list endpoint. If a scan cannot be queued after saving a draft, error.details.brand_ref identifies that draft; resume it instead of creating a duplicate. This is the sandbox environment: registrations and carrier submissions are simulated, so nothing reaches The Campaign Registry and no charges are incurred.