> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Errors

When a request fails, the API returns a standard [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
`application/problem+json` body — never an HTML page or an unstructured string:

```json
{
  "type": "https://docs.usglobalmail.com/api/problems/validation_error",
  "title": "Your request parameters did not validate.",
  "status": 422,
  "code": "validation_error",
  "request_id": "req_8f3c2a1b9d",
  "instance": "/v1/mails",
  "detail": "is_read must be a boolean.",
  "errors": [
    { "field": "is_read", "message": "must be a boolean" }
  ]
}
```

The `type` is a dereferenceable URL — open it for a full explanation of that problem. Browse them all
under [Problem types](/api/problems/overview).

| Field        | Meaning                                                                     |
| ------------ | --------------------------------------------------------------------------- |
| `type`       | A URI identifying the problem type (links into this documentation).         |
| `title`      | A short, human-readable summary of the problem type.                        |
| `status`     | The HTTP status code, repeated for convenience.                             |
| `detail`     | A human-readable explanation specific to this occurrence.                   |
| `code`       | A stable, machine-readable string to branch on. Prefer this over `title`.   |
| `request_id` | Quote this when contacting support — it pins the exact request in our logs. |
| `errors`     | Present on `422` — the list of per-field validation failures.               |

## Status codes

| Status | `code`                                                           | When                                                                                                                |
| ------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `400`  | [`bad_request`](/api/problems/bad_request)                       | Malformed request the schema can't accept.                                                                          |
| `401`  | [`unauthorized`](/api/problems/unauthorized)                     | Missing, malformed, or invalid API key.                                                                             |
| `403`  | [`forbidden`](/api/problems/forbidden)                           | Authenticated, but not allowed to perform this action.                                                              |
| `404`  | [`not_found`](/api/problems/not_found)                           | No such resource (or not visible to this key).                                                                      |
| `405`  | [`method_not_allowed`](/api/problems/method_not_allowed)         | The HTTP method isn't allowed on this endpoint.                                                                     |
| `409`  | [`conflict`](/api/problems/conflict)                             | The request conflicts with the resource's current state.                                                            |
| `415`  | [`unsupported_media_type`](/api/problems/unsupported_media_type) | The request `Content-Type` isn't supported.                                                                         |
| `422`  | [`validation_error`](/api/problems/validation_error)             | Well-formed request, but a field failed validation.                                                                 |
| `429`  | [`rate_limited`](/api/problems/rate_limited)                     | Too many requests — see [Rate limits](/guides/core-concepts/rate-limits).                                           |
| `500`  | [`internal_error`](/api/problems/internal_error)                 | Something failed on our side — check [System status](/guides/core-concepts/system-status), then retry with backoff. |
| `502`  | [`bad_gateway`](/api/problems/bad_gateway)                       | An upstream service returned an invalid response.                                                                   |
| `503`  | [`service_unavailable`](/api/problems/service_unavailable)       | Temporarily unavailable — retry after a short delay.                                                                |
| `504`  | [`gateway_timeout`](/api/problems/gateway_timeout)               | An upstream service timed out.                                                                                      |

Each `code` links to a page with common causes, resolution steps, and an example body. Browse them all
under [Problem types](/api/problems/overview).

## Handling errors

Branch on the machine-readable `code`, not the human-readable `title` (titles may be reworded):

**`TypeScript`**

```typescript title="TypeScript"
import { UsgmError } from "@usgm/sdk";

try {
  await usgm.mails.get("80421");
} catch (err) {
  if (err instanceof UsgmError && err.code === "not_found") {
    // handle a missing mail item
  }
  throw err;
}
```

**`Python`**

```python title="Python"
from usgm import UsgmError

try:
    usgm.mails.get("80421")
except UsgmError as err:
    if err.code == "not_found":
        ...  # handle a missing mail item
    raise
```

> **Note**
>
> Always log the `request_id` from failed responses. It's the fastest way for USGM support to trace
> what happened.