Errors

The API uses conventional HTTP status codes and returns a JSON error envelope on every failure.

Error object

{
  "object": "error",
  "type": "invalid_request",
  "message": "content_type is required",
  "param": "content_type",
  "request_id": "req_9fc31a2b8e4d75"
}

Fields:

• object is always "error".
• type is one of the machine-readable codes below.
• message is a human-readable summary suitable for logging.
• param (optional) names the offending field on validation errors.
• request_id echoes the value in the X-Request-Id response header. Include it when contacting support.

Status codes

Status	type	Meaning
400	invalid_request	Malformed JSON or missing required fields.
401	authentication_failed	Missing, revoked, or malformed API key.
402	subscription_inactive	Workspace subscription is past due or cancelled. Response body includes upgrade_required: true and current_plan.
403	plan_feature_unavailable	The workspace plan does not include the requested feature. Same upgrade_required + current_plan fields.
404	not_found	Resource does not exist or is not visible to this workspace.
409	conflict	State transition rejected (for example, launching a campaign that is already active).
422	unprocessable_entity	Passes basic validation but violates a business rule.
429	rate_limit_exceeded	See Rate limits.
500	internal_error	Unexpected server error. Safe to retry after a short delay.

Handling 402 and 403

The API distinguishes between billing problems and plan problems on purpose.

• 402 means the workspace has a plan that would include this feature, but billing is not current. Nudge the user to update their payment method.
• 403 means the plan itself does not include the feature. Nudge the user to upgrade.

Both responses include the same helper fields so you can render one banner:

{
  "object": "error",
  "type": "plan_feature_unavailable",
  "message": "The API is available on the Pro plan and above.",
  "upgrade_required": true,
  "current_plan": "starter"
}

Validation errors

invalid_request and unprocessable_entity responses may include an errors array when more than one field is at fault:

{
  "object": "error",
  "type": "invalid_request",
  "message": "Multiple fields failed validation",
  "errors": [
    { "param": "platforms", "message": "must contain at least one platform" },
    { "param": "scheduled_at", "message": "must be in the future" }
  ]
}