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`	A permission, resource context, or church plan prevents the action.	Inspect the error code and plan metadata before asking an administrator to review access.
`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.

Plan access denials

Protected v1 requests require the church’s plan to include Platform Integrations, even when the API key and member token are valid. A plan-related 403 includes error_code: "plan_product_unavailable" and plan_access metadata. For example, these fields identify a plan restriction:

{
  "success": false,
  "error_code": "plan_product_unavailable",
  "plan_access": {
    "product": "platform_integrations",
    "current_plan": "standard",
    "recommended_plan": "large"
  }
}

Ask the church’s authorized administrator to review the plan and product access. Signing the member in again, rotating credentials, or automatically retrying the same request will not change that entitlement. For other 403 responses, review the endpoint’s permission and resource-context requirements.

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

Plan access denials

Retry guidance

​Response conventions

​Status envelopes

​Pagination

​Error bodies

​Common status codes

​Plan access denials

​Retry guidance

Response conventions

Status envelopes

Pagination

Error bodies

Common status codes

Plan access denials

Retry guidance