API: Errors & Rate Limits

Pingovo uses standard HTTP status codes, and every error body carries a machine-readable error code plus a human-readable message. Branch on the status and the code; show the message to people.

HTTP status codes

Rate limits

Your plan sets how many requests you can make per minute and per day. The allowance is shared by all of your API keys, so a second key does not buy more. A key can additionally be given its own per-minute cap to stop one integration starving another.

Every authenticated response tells you where you stand:

A rate-limited call never reaches the endpoint, so it is never charged:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{
  "success": false,
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded (60 requests per minute). Retry after 23s.",
  "retry_after_seconds": 23,
  "limit": 60,
  "window": "minute"
}

Handling 429 properly

Wait the number of seconds in Retry-After, then retry. If the header is missing, back off exponentially. Do not retry in a tight loop — against AUTH_THROTTLED that only extends the block.

# -i prints the response headers: X-RateLimit-Limit, X-RateLimit-Remaining,
# X-RateLimit-Reset on every call, and Retry-After on a 429.
curl -i https://pingovo.com/api/v1/credits \
  -H "X-API-Key: YOUR_API_KEY"

Authentication errors

Insufficient credits

A 402 from /send tells you exactly how short you are:

{
  "success": false,
  "error": "INSUFFICIENT_CREDITS",
  "message": "Not enough credits to send this email",
  "credits_required": 11,
  "credits_available": 4,
  "tracking_credits": 10
}

tracking_credits appears only when you asked for tracking and is the part of credits_required that tracking accounts for.

Verify endpoint errors

Reliability tips

• Store the ids. Keep send_id and request_id next to your own record. They are how you and support find a specific email.
• Retry only what is safe. A 429 or 5xx means the email was not sent, but a timeout leaves it unknown: check GET /sends?q=recipient before resending, or you may send a customer the same email twice.
• Do not retry 4xx. The same request will fail the same way.
• Set client timeouts above 50 seconds if you use delay_between_emails.