Errors

When a request fails, the API returns a standard RFC 9457 application/problem+json body — never an HTML page or an unstructured string:

1
{
2
  "type": "https://docs.usglobalmail.com/api/problems/validation_error",
3
  "title": "Your request parameters did not validate.",
4
  "status": 422,
5
  "code": "validation_error",
6
  "request_id": "req_8f3c2a1b9d",
7
  "instance": "/v1/mails",
8
  "detail": "is_read must be a boolean.",
9
  "errors": [
10
    { "field": "is_read", "message": "must be a boolean" }
11
  ]
12
}

The type is a dereferenceable URL — open it for a full explanation of that problem. Browse them all under Problem types.

Status codes

For the complete list — including 405, 409, 415, 502, 503, 504 — and a page per type, see Problem types.

Handling errors

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

1
import { UsgmError } from "@usgm/sdk";
2
3
try {
4
  await usgm.mails.get("80421");
5
} catch (err) {
6
  if (err instanceof UsgmError && err.code === "not_found") {
7
    // handle a missing mail item
8
  }
9
  throw err;
10
}