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:

{
  "status": "Success",
  "data": {}
}

Some endpoints use a boolean success field:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

Get Started

Endpoints

Pagination and Errors

Response conventions

Status envelopes

Error bodies

Common status codes

Retry guidance

​Response conventions

​Status envelopes

​Pagination

​Error bodies

​Common status codes

​Retry guidance

Response conventions

Status envelopes

Pagination

Error bodies

Common status codes

Retry guidance