API errors

Every error the Partner API returns is an RFC 7807 application/problem+json body:

{
  "type": "https://docs.rostergiving.com/errors/bad-request",
  "title": "Bad Request",
  "detail": "church_id is required",
  "request_id": "req_1a2b3c..."
}

type links to the pages below. Always log request_id — it is how support correlates your call with our traces. Every response to an authenticated call, success included, carries the same reference in the X-Request-Id header, so you can log it for every call your key makes.

Some errors come from the gateway in front of the API, not from the API itself: its throttle, shared by every partner (429), or a call the API did not answer in time (500 or 503). They are plain JSON, such as {"message":"Too Many Requests"}, with no type, no request_id and no Retry-After. Retry them with exponential backoff, starting at about one second, and the same Idempotency-Key. Log the UTC time and the operation (method and path) and include both when you write to support; these responses carry no request_id.

The gateway also answers two requests that never reach the API. A path it cannot parse, such as one containing %zz, gets 400 with an HTML body: fix how you build the URL, and do not retry it unchanged. A browser preflight (OPTIONS) gets 403 with an empty body: the API takes calls from your backend, not from a web page.

None of these gateway responses carries X-Request-Id, Roster-Api-Version or RateLimit-*, so there is no X-Request-Id to log for them. Every response the API itself sends carries X-Request-Id and Roster-Api-Version.