Errors and status codes

What each response code means and how to handle it.

Harepost uses standard HTTP status codes. Errors return a JSON body with an error field, and sometimes a detail field with more context.

{
  "error": "destination domain is not verified",
  "detail": "Verify your-app.com before sending to it..."
}

Status codes

Code	Meaning
`200`	Success on read and verify endpoints.
`201`	Created: a new account, or a domain added.
`202`	A send was accepted and queued. Delivery happens after this.
`400`	The request was malformed. Check the `error` field.
`401`	Missing or invalid API key.
`403`	The target domain is not verified for your account.
`404`	The resource does not exist or is not on your account.
`405`	Wrong HTTP method for that endpoint.
`409`	A domain’s TXT record was not found yet during verification.
`429`	Rate limit exceeded.

Common errors

401, missing or invalid API key

Your Authorization header is absent or the key is wrong. Send it as Authorization: Bearer hp_live_.... Keys cannot be recovered after signup, so if you lost it, create a new one.

403, domain not verified

You tried to send to a domain your account has not verified. The detail field names the host and the steps to fix it. See verify a domain.

400 on send

The request body did not validate. Common causes: malformed JSON, a missing target, a target that is not https, a target that resolves to a private or non-routable address, or a method outside the allowed set.

429, rate limit exceeded

You sent faster than your account’s per-minute limit. The response includes a Retry-After header in seconds. Back off for that long, then continue. Spacing out your sends avoids this.

Handling errors in code

Treat the families differently:

A 4xx other than 429 means the request itself is wrong. Fix it before retrying, since sending the same thing again will fail the same way.
A 429 is temporary. Honor Retry-After and try again.
A 5xx from the Harepost API itself is rare and temporary; a short backoff and retry is reasonable.

Note this is about errors from the Harepost API when you call it. How Harepost handles errors from your endpoint during delivery is a separate thing, covered in retries and delivery.