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.

{
  "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

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.

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.
• /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.

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