---
title: Errors and retries | SendHQ Docs
description: Parse the standard JSON error envelope and decide when a retry is safe.
canonical: https://sendhq.cc/docs/errors
last-updated: 2026-09-07
---
# Errors and retries

Parse the standard JSON error envelope and decide when a retry is safe.

## Error envelope

JSON API failures use one top-level `error` object with a human-readable `message`, the numeric HTTP `status`, and an optional stable `code`. The OpenAPI contract references this schema for expected and unexpected failures.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "A verified From domain is required",
    "status": 403
  }
}
```

## Client errors

Correct `400` input errors before retrying. Replace or revoke invalid credentials after `401`. A `402` requires paid entitlement, `403` marks a policy or permission boundary, `404` is a missing tenant-scoped resource, `409` is a state or idempotency conflict, `413` exceeds attachment limits, and `422` covers validation or suppression.

## Retry decisions

Do not automatically retry authentication, validation, suppression, or conflict failures. A `423` means the exact From identity is paused; stop that stream, correct its recipients, and retry only after its rolling metrics clear. A caller may retry a transient `429`, `502`, or `503` response with bounded exponential backoff and jitter. Preserve the same `Idempotency-Key` and identical JSON payload when retrying one logical send.

## Support context

Record the request time, route, HTTP status, SendHQ resource ID, and non-secret error fields. Never include an API key, session cookie, message body, or recipient list in a support report.