Error codes

The integrator API uses standard HTTP status codes. Validation errors return JSON with per-field detail.

Summary

Code	Meaning	Recommended action
`202`	Accepted	Message queued; check status in the panel.
`400`	Bad request	Review JSON body and headers.
`401`	Unauthenticated	Verify `Authorization: Api-Key …`.
`403`	Forbidden	Check `X-Organization-ID` and project permissions.
`404`	Not found	Template or resource missing in tenant.
`422`	Unprocessable entity	Valid format but rejected by business rules.
`429`	Rate limit exceeded	Wait and retry with exponential backoff.
`5xx`	Server error	Retry; contact support if it persists.

Common causes:

{
	"detail": "Authentication credentials were not provided."
}

The API key is valid but cannot operate on the given organization, or the plan blocks more sends.

The template slug does not exist on the project linked to the API key.

Example when the template is missing or the channel is invalid:

{
	"template": ["Template not found or inactive."],
	"to": ["This field is required."]
}

Common fields on POST /api/v1/send/:

Field	Rule
`template`	Active template slug in the project.
`to`	Valid destination email.
`channel`	Currently `email`.
`data`	JSON object with template variables.

Public send is limited per API key (default 120 requests/minute, configurable via NOTIFY_PUBLIC_SEND_RATE).

{
	"detail": "Request was throttled. Expected available in 42 seconds."
}

Retry-After headers may be included. Use Idempotency-Key for safe retries.

{
	"message_id": 1042,
	"status": "queued",
	"celery_task_id": "a1b2c3d4-...",
	"idempotent_replay": false
}

If a 5xx persists, note message_id, UTC time, and the Idempotency-Key used when contacting support.