Error codes

HTTP error format and common causes.

Error responses follow a uniform JSON format:

{
  "statusCode": 403,
  "message": "Missing required API key scope: email:send",
  "path": "/emails/send",
  "timestamp": "2026-06-30T12:00:00.000Z"
}

HTTP codes

Code	Meaning
400	Validation failed (required field, invalid email)
401	Invalid or expired JWT or API key
403	Insufficient scope, role, or unauthorized tenant
404	Resource not found
409	Conflict (duplicate, invalid state)
422	Business rule (e.g. suppressed recipient)
429	Global rate limit or monthly quota exceeded

Quota exceeded (429)

When you exceed 110% of the monthly limit:

{
  "statusCode": 429,
  "message": "Monthly email quota exceeded (115%). Upgrade your plan to continue sending.",
  "quota": {
    "limit": 100,
    "used": 115,
    "percentage": 115
  }
}

Rate limit

In production: ~300 requests/minute per IP or JWT user (configurable). Headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1719763200

Public auth routes (/auth/login, /auth/register) have a stricter limit: 15 requests / 15 minutes.

SDK

The mailingcore-js package throws MailingCoreError with .status and .detail for client-side handling.