Responses and Errors

Success Envelope

Single-resource and write responses use a standard success envelope:

{
  "success": true,
  "message": "Member retrieved successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011"
  }
}

List responses include pagination metadata:

{
  "success": true,
  "message": "Members retrieved successfully",
  "data": [],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 47,
    "itemsPerPage": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Error Envelope

{
  "success": false,
  "message": "Invalid API key"
}

Validation failures may include an errors array.

{
  "success": false,
  "message": "Name is required; Valid email is required",
  "errors": [
    {
      "type": "field",
      "msg": "Name is required",
      "path": "name",
      "location": "body"
    },
    {
      "type": "field",
      "msg": "Valid email is required",
      "path": "email",
      "location": "body"
    }
  ]
}

For public API validation failures, message contains an actionable summary suitable for displaying directly in an integration client such as Zapier. When errors is present, use each item's path and msg to associate the reason with a request field.

The error envelope remains backwards compatible: success, message, and the optional errors array retain their existing types. Existing integrations that already read errors can continue to do so, while integrations that only display message receive a more useful reason.

Typical validation messages explain both the invalid value's expected format and where to obtain identifiers. For example:

{
  "success": false,
  "message": "memberId must be the RemyPass member _id returned by the members API",
  "errors": [
    {
      "type": "field",
      "msg": "memberId must be the RemyPass member _id returned by the members API",
      "path": "memberId",
      "location": "body"
    }
  ]
}

Rate limit responses may include limit, remaining, resetTime, and retryAfter.

Common Status Codes

• 200: Request succeeded
• 201: Resource created
• 400: Validation or bad request; inspect message and, when present, errors
• 401: Missing, invalid, inactive, or expired API key
• 403: Permission, plan, or access failure
• 404: Resource or endpoint not found
• 429: Rate limit exceeded
• 500: Server error; retry the request and contact support if it continues

All examples in the endpoint reference show the response fields available for that endpoint.