Error Codes

PostMTA surfaces errors at two layers: the SMTP layer (during message delivery) and the REST API layer (when your application calls the PostMTA API). This page documents every error code you may encounter and how to resolve each class of error.

SMTP Error Codes

Overview

When PostMTA delivers a message to a recipient MTA, the recipient MTA responds with an SMTP reply code. PostMTA classifies these codes as described below. The table covers codes most commonly returned by major inbox providers and relay servers.

SMTP Reply Code Reference

Enhanced Status Codes

The enhanced status code (e.g., 5.1.1, 4.5.3) provides a machine-readable sub-classification of the SMTP reply code. PostMTA maps these to internal bounce reasons:

REST API Error Responses

Error Response Schema

All PostMTA REST API errors return a JSON body with a consistent structure:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the rate limit of 1000 requests per minute.",
    "status": 429,
    "details": {
      "limit": 1000,
      "window": "1m",
      "retry_after_seconds": 42
    },
    "request_id": "req_01HXABC123DEF456"
  }
}

Error Code Reference

Common Error Scenarios and Resolution

Connection Timeout

PostMTA will close a connection that receives no data for 30 seconds during the SMTP transaction. If you see timeout errors:

• Check whether the recipient MTA is reachable (telnet mx.example.com 25)
• Verify DNS MX resolution is working correctly
• Reduce message size if sending very large HTML bodies with many images
• Check whether a firewall is dropping packets to port 25

TLS Handshake Failure

If delivery attempts fail with a TLS negotiation error:

SSL alert: certificate verify failed (code: 20)
TLS connection could not be established

Resolution steps:

• Verify the recipient MX certificate is not expired
• Ensure your PostMTA instance has an up-to-date CA certificate bundle
• Check whether the recipient requires a specific TLS version (TLS 1.2 minimum is enforced)

SPF / DKIM Failure at Recipient

When a recipient server reports SPF or DKIM failure:

• SPF: verify your sending domain's DNS has an SPF record that includes all PostMTA egress IPs
• DKIM: verify the DKIM record is published in DNS and the private key is correctly configured in PostMTA
• DMARC: align your From domain with the SPF and DKIM selector domains

Rate Limit Errors (429)

Rate Limit Types

Handling Rate Limits

When you receive a 429 response, read the Retry-After header (integer seconds) and delay accordingly. Implement exponential backoff for resilience:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1750272030

Burst vs. Sustained Limits

PostMTA applies both burst (per-second) and sustained (per-minute/per-day) limits. Even if your per-minute average is within limit, a short burst above the burst threshold will return 429. Distribute message injection evenly rather than sending in large batches.

Authentication Errors (401 / 403)

Missing API Key

curl https://api.postmta.com/v1/keys
# Returns: 401 {"error": {"code": "AUTHENTICATION_REQUIRED", ...}}

Always include the Authorization header:

curl https://api.postmta.com/v1/keys \
  -H "Authorization: Bearer pmta_l...xxxx"

Wrong Key Scope

Using a key with insufficient scopes returns 403 INSUFFICIENT_PERMISSIONS. Available scopes:

• keys:read — list and view API keys
• domains:manage — add, verify, and remove sending domains
• messages:send — inject messages
• analytics:read — read analytics data
• webhooks:manage — create and update webhook endpoints

Key Rotation

API keys can be rotated without downtime by creating a new key, updating your application, and then revoking the old key once traffic has switched over.

Quota Exceeded Errors

Credit Limit Exceeded (429)

{
  "error": {
    "code": "CREDIT_LIMIT_EXCEEDED",
    "message": "Workspace has insufficient credits. Required: 150. Available: 23.",
    "status": 429,
    "details": {
      "required": 150,
      "available": 23,
      "top_up_url": "/app/credits"
    }
  }
}

Top up via the dashboard at /app/credits or via the API:

curl -X POST https://api.postmta.com/v1/credits/topup \
  -H "Authorization: Bearer pmta_l...xxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "payment_method_id": "pmt_01HXABC123DEF456"}'

Sending Domain Quota

Each workspace plan includes a maximum number of verified sending domains. Adding a new domain beyond this limit returns:

{
  "error": {
    "code": "DOMAIN_QUOTA_EXCEEDED",
    "message": "Plan limit of 5 sending domains reached. Upgrade to Growth to add more.",
    "status": 400
  }
}

IP Pool Quota

Each workspace plan includes a maximum number of dedicated IPs. Exceeding this returns:

{
  "error": {
    "code": "IP_POOL_QUOTA_EXCEEDED",
    "message": "Plan limit of 2 dedicated IPs reached.",
    "status": 400
  }
}