> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thefaithapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination and Errors

> Handle paginated collections, validation failures, authorization errors, and safe retries.

# Response conventions

The API uses a small number of response shapes. Always branch on the HTTP status code first, then inspect the JSON body for endpoint-specific details.

## Status envelopes

Many member-scoped endpoints return:

```json theme={null}
{
  "status": "Success",
  "data": {}
}
```

Some endpoints use a boolean success field:

```json theme={null}
{
  "success": true,
  "data": {}
}
```

Treat both shapes as endpoint contracts; do not assume every endpoint uses the same top-level field names.

## Pagination

Collection endpoints generally accept `page` and `per_page`. `per_page` is capped by the endpoint, commonly at 100.

Laravel-style collection responses include the records in `data` plus pagination metadata:

```json theme={null}
{
  "current_page": 1,
  "data": [],
  "last_page": 1,
  "per_page": 20,
  "total": 0,
  "next_page_url": null,
  "prev_page_url": null
}
```

Some endpoints wrap that paginator inside a success envelope:

```json theme={null}
{
  "status": "Success",
  "data": {
    "current_page": 1,
    "data": [],
    "per_page": 20,
    "total": 0
  }
}
```

Follow the schema on each endpoint page and stop when `next_page_url` is `null` or `current_page` equals `last_page`.

## Error bodies

Depending on the endpoint, the human-readable message can appear in `message`, `error`, or `error_message`:

```json theme={null}
{
  "status": "Error",
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."]
  }
}
```

Use the field-specific `errors` object to guide form corrections. Do not show raw server error details to end users.

## Common status codes

| Status | Meaning                                                              | Recommended handling                                                                                |
| ------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | The request conflicts with the resource's current state.             | Correct the action or refresh the resource before retrying.                                         |
| `401`  | API key or bearer token is missing, invalid, expired, or mismatched. | Re-authenticate the member and verify both credentials belong to the same church.                   |
| `403`  | The member is authenticated but lacks permission.                    | Do not retry without a permission or resource-context change.                                       |
| `404`  | The resource does not exist in the authenticated church.             | Refresh local state and stop retrying the same identifier.                                          |
| `422`  | One or more inputs failed validation.                                | Display safe field-level validation messages.                                                       |
| `429`  | The rate limit was exceeded.                                         | Back off and retry after the server's retry window.                                                 |
| `500`  | An unexpected server error occurred.                                 | Retry read-only requests with bounded exponential backoff; avoid automatically repeating mutations. |

## Retry guidance

* Retry `429` and transient `5xx` responses with exponential backoff and jitter.
* Cap retry attempts and set request timeouts.
* Retry safe reads automatically only when your product can tolerate stale or delayed data.
* Do not automatically retry registration, signup, or other mutations unless your application can prove the first request did not succeed.
* Log a request correlation identifier if one is returned, but never log API keys, member tokens, or personal response bodies.