How do I troubleshoot API errors?

Updated Nov 2, 2026

The status code and the code field tell you what went wrong.

Status codes

  • 400: a business rule was violated, for example a duplicate contact email.
  • 401: invalid API key or inactive organization.
  • 403: not allowed, for example a fromEmail that is not one of your senders, or CONTACT_LIMIT_REACHED.
  • 404: not found, for example the contact to unsubscribe.
  • 422: missing or invalid fields, or unexpected keys.
  • 429: a sending limit was reached; nothing was sent.
  • 500: internal or email provider error.

429 codes

  • SENDER_HOURLY_LIMIT / SENDER_DAILY_LIMIT: that sender reached its limit. Retry after the Retry-After header.
  • EMAIL_QUOTA_EXCEEDED: an account-wide limit (plan allowance or API rate) was reached.
  • SENDER_PROVIDER_BLOCKED: the sender is paused for the recipient's provider; retry after retryAt.
  • API emails are never queued for later.

Avoiding duplicate sends

  • After a timeout or network error, retry with the same optional Idempotency-Key and the same payload, so the email is not sent twice.

More details in the FAQ

The FAQ is in the MailRush.io app under Support (sign-in required).

Related articles

Didn't find what you need?

Sign in to MailRush.io and open a support ticket, and our support team will get back to you.

Contact support