Troubleshoot API errors

Error Codes

A comprehensive reference for all error codes returned by the Mailpipe API, with explanations and resolution steps.

Error Response Format

All API errors return a JSON body with an error field:

Error Response

{
  "error": "Validation failed: to.0.email: Invalid email"
}

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`400`	Bad Request	Invalid request body, missing required fields, or validation error
`401`	Unauthorized	Missing or invalid API key / session token
`403`	Forbidden	API key lacks required scope or doesn't belong to the organization
`404`	Not Found	Resource doesn't exist (mailbox, domain, message)
`429`	Too Many Requests	Rate limit exceeded — check `Retry-After` header
`500`	Internal Error	Unexpected server error — retry or contact support
`502`	Bad Gateway	Email provider returned an error (Resend, Postmark, etc.)

Common Errors & Solutions

"Authorization header is required"

You forgot to include the Authorization header.

Fix

curl -H "Authorization: Bearer mp_live_xxx" ...

"Invalid key format"

The API key must match the format mp_live_* or mp_test_*. If you're calling from the web app, ensure you're passing a valid session token.

"No provider configuration found for this domain"

Your domain doesn't have an email provider configured. Go to Settings → Domains and set up a provider (Resend, Postmark, SendGrid, or Mailgun).

"Validation failed: to.0.email: Invalid email"

The to field must be an array of objects with a valid email field.

Correct Format

{
  "to": [{ "email": "user@example.com", "name": "User" }]
}

"Domain is not verified"

You need to verify your domain's DNS records before sending email. Check your domain settings and ensure MX, SPF, and DKIM records are correctly configured.

Debugging Tips

Use mp_test_* keys during development — they don't send real emails
Check the response body — error messages include specific field paths for validation errors
For 502 errors, the upstream provider (Resend, Postmark) may have issues — check their status pages
Enable verbose logging in your SDK client to see full request/response data

Still have questions?

We can help with anything from setup to scaling.

Contact support