Errors

Failed requests return a 4xx or 5xx status and a JSON body:

{
    "error": {
        "type": "validation_error",
        "code": "domain_not_verified",
        "message": "The sender's domain is not verified.",
        "param": "from",
        "doc_url": "https://docs.pulse-send.jiordiviera.me/errors#domain_not_verified"
    }
}

Field	Description
`type`	The category. It decides the HTTP status.
`code`	A stable, specific code. Branch your logic on this one.
`message`	A readable explanation. It may change; don’t parse it.
`param`	The request field at fault, when there is one.
`doc_url`	A link to the code below.

Every response also carries an X-Request-Id header. Include it when you contact support.

Types

Type	Status	Retry?
`authentication_error`	401	No. Fix the key.
`insufficient_credits`	402	After a top-up.
`permission_error`	403	No.
`not_found`	404	No.
`idempotency_error`	409	Depends on the code.
`validation_error`	422	No. Fix the request.
`rate_limit_error`	429	Yes, after `Retry-After`.
`api_error`	500	Yes, with backoff and an idempotency key.

Codes

missing_api_key

No Authorization: Bearer ps_… header. See Authentication.

invalid_api_key

The key doesn’t exist or was revoked. Create a new one in the dashboard.

insufficient_credits

The live send needs more credits than your team has. Nothing was sent. Top up and retry.

missing_scope

The key doesn’t have the scope this endpoint needs, for example emails:send. See Scopes.

team_paused

Sending is paused for your team, usually after high bounce or complaint rates (see Sending reputation). Contact support.

resource_missing

The ID doesn’t match anything your team owns.

idempotency_key_reused

You reused an Idempotency-Key with a different body. Use a new key for a new request. See Idempotency.

idempotency_in_progress

A request with the same Idempotency-Key is still running. Wait a moment and retry.

idempotency_key_too_long

Idempotency-Key is limited to 255 characters.

invalid_parameter

A field is missing or malformed. param names it and message says what’s wrong.

missing_body

The email has neither html nor text. Send at least one.

too_many_recipients

More than 50 recipients across to, cc and bcc. Split the send.

domain_not_verified

With a live key, the from address must belong to a verified domain.

all_recipients_suppressed

Every recipient is on your suppression list after a hard bounce or a complaint. Nothing was sent.

rate_limited

More than 10 requests per second on this key. Wait Retry-After seconds.

internal_error

Something broke on our side. Retry with backoff, using an idempotency key. If it persists, contact support with the X-Request-Id.

Overview

Emails

Types

Codes

missing_api_key

invalid_api_key

insufficient_credits

missing_scope

team_paused

resource_missing

idempotency_key_reused

idempotency_in_progress

idempotency_key_too_long

invalid_parameter

missing_body

too_many_recipients

domain_not_verified

all_recipients_suppressed

rate_limited

internal_error

​Types

​Codes

​missing_api_key

​invalid_api_key

​insufficient_credits

​missing_scope

​team_paused

​resource_missing

​idempotency_key_reused

​idempotency_in_progress

​idempotency_key_too_long

​invalid_parameter

​missing_body

​too_many_recipients

​domain_not_verified

​all_recipients_suppressed

​rate_limited

​internal_error

Types

Codes

missing_api_key

invalid_api_key

insufficient_credits

missing_scope

team_paused

resource_missing

idempotency_key_reused

idempotency_in_progress

idempotency_key_too_long

invalid_parameter

missing_body

too_many_recipients

domain_not_verified

all_recipients_suppressed

rate_limited

internal_error