Errors

Errors and rate limits

Every error is an RFC 7807 application/problem+json body, with the standard title, status, detail, and instance fields alongside an errorCode extension. Branch on errorCode, not on detail - the message text can change; the code is the contract.

Two statuses are the exception, because neither reaches the API itself. A request body over 10 MB is refused with a bare 413 before it is parsed, and 429 comes from the rate limiter. Both answer without an errorCode, so branch on the status for those two.

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is invalid or revoked.",
  "instance": "/api/v1/notifications/send",
  "errorCode": "api_keys.invalid",
  "correlationId": "0f2b8a1e-6c9d-4b3a-9e7f-2d4c8a1b6e3f",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Validation failures

A send or preview request that fails validation always carries the umbrella code notifications.validation_failed as its errorCode, so the documented promise that every error has one holds without exception. Alongside it, an errorCodes array lists every specific rule that actually fired - a single request can trip more than one at once, for example a missing tags field and an invalid recipient together. Branch on the umbrella code to detect "this request was malformed," then read errorCodes for which of the codes below caused it. The standard errors field is still present too, mapping each request property to its message text - useful for surfacing something to a human, but not for branching on.

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Tags": ["Tags collection is required."],
    "EmailOptions.To[0]": ["To recipient must be a valid email address."]
  },
  "errorCode": "notifications.validation_failed",
  "errorCodes": [
    "notifications.tags_required",
    "notifications.email.to_invalid"
  ],
  "instance": "/api/v1/notifications/send",
  "correlationId": "0f2b8a1e-6c9d-4b3a-9e7f-2d4c8a1b6e3f"
}

Every error code

For the distribution-list and recipient-variable codes above, see Distribution lists for the request shapes that trigger them.

Email field codes

Per-recipient validation on emailOptions. to, cc, bcc, and overrideRecipients are each checked only once you send a non-empty list for that field - omitting the field entirely never triggers these. The one exception is notifications.email.too_many_recipients, which counts all four lists together rather than checking any one of them, so splitting a large send across the fields does not avoid it.

Attachment field codes

Per-attachment validation on emailOptions.attachments, checked for each entry in the array.

Rate limits

Limits are fixed windows, reset every minute, and return 429 once exceeded. The numbers below are the platform defaults CommuniQueue ships with - they're configurable per deployment, so treat them as what you should expect out of the box rather than a number you can rely on exactly.

• /notifications/send and /notifications/preview share a default budget of 300 requests per minute per API key.
• Those two routes also share a default of 300 requests per minute per source IP, counted across every key. One key from one address never meets it; several keys behind one office network or one CI runner can, and the fix is to spread the traffic rather than to add keys.
• /api-keys/validate defaults to 120 requests per minute per source IP, since it is a key-validation check rather than a send.
• Inbound webhook intake defaults to 600 requests per minute per source IP.
• One-click unsubscribe defaults to 120 requests per minute per source IP.
• The /distribution-lists routes default to 120 requests per minute per API key and, separately, 120 per minute per source IP, a budget of their own that list management and sends never share.

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Try again later.",
  "instance": "/api/v1/notifications/send"
}