ParasendDocs
Sign in Start free

Handling errors

Parasend answers with the usual HTTP status codes: 2xx worked, 4xx means the request needs to change, 5xx means something went wrong on our side. Every error has the same body:

{
  "error": {
    "type": "invalid_request",
    "code": "recipient_phone_invalid",
    "message": "recipient.phone must be in E.164 format (e.g. +3546661234).",
    "param": "recipient.phone",
    "doc_url": "https://parasend.com/docs/errors/recipient_phone_invalid",
    "request_id": "req_01M6P3QD4H8WZ2KX7N1R9T5V3B"
  }
}
FieldWhat it is
typeThe group the error belongs to (below).
codeA stable, specific code. Branch on this, never on message. Every code has its own page under error codes.
messageA sentence for a person to read. It can change.
paramWhen one parameter caused it, its name, as a dotted path such as recipient.phone.
doc_urlThe code's page in these docs: what it means and what to do.
request_idThe request's ID, also in the Request-Id header. Give it to us when you ask for help.

A few errors carry more fields, named on their own page.

Error types

TypeStatusWhat to do
invalid_request400, sometimes 404Fix the request. code and param say what is wrong.
authentication_error401Check the API key. See authentication.
permission_error403The key lacks a permission, or the action is not allowed for this account.
not_found404No such object in this mode, or no such route.
conflict409The object's state does not allow this now, for example a reminder before the first notice has gone out (remind_state_invalid).
payload_too_large413The body or file is too large.
rate_limited429Wait, then try again. See rate limits.
api_error500, 503Try again with the same Idempotency-Key. If it keeps happening, contact us with the request_id.

Retrying safely

  • Retry 429, 500, 503 and network failures, with exponential backoff. When the answer has a Retry-After header, wait at least that many seconds.
  • Send the same Idempotency-Key when you retry a POST. If the first attempt did go through, you get its answer back instead of a second delivery. See idempotency.
  • Do not retry other 4xx errors unchanged: they will fail the same way.

Request IDs

Every answer carries a Request-Id header, such as req_01M6P3QD4H8WZ2KX7N1R9T5V3B. Log it with your own record of the call. You can also send your own Request-Id starting with req_, and Parasend uses it.