Neighborly Software API

Error Handling Overview

The API is designed to return helpful and consistent error information to clients:

• Standard REST endpoints return typical HTTP error codes (e.g., 400, 404, 500) along with detailed messages and suggestions.
• RPC action endpoints (e.g., approving a draw, adding a loan transaction) may return 409 Conflict when a business logic conflict occurs.

---

Common Status Codes

Status Code	Description	Usage Example
400	Bad Request	Missing required parameters, invalid data types
401	Unauthorized	Invalid or missing access token
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Business rule conflict (e.g., approving an already-approved draw)
500	Internal Server Error	Unhandled exception or server-side issue

---

Error Response Format

All error responses follow this structured format:

Code
 
{
  "statusCode": 404,
  "error": {
    "message": "The requested resource could not be found.",
    "details": "No draw found for id 9999999.",
    "suggestion": "Check the resource ID and try again. Contact support@neighborlysoftware.com for further assistance."
  }
}

Field Definitions

Field	Description
statusCode	Standard HTTP error code (400, 404, 500, etc.)
message	High-level error message or HTTP description
details	Specific information about the failed request (e.g., missing parameters)
suggestion	Recommended next steps for resolution

---

RPC-Style Endpoint Errors

RPC-like actions such as approving or rescinding a draw or adding a loan transaction may encounter business logic conflicts.

In these situations:

• The API returns a 409 Conflict status code.
• The response includes details about the specific business conflict (e.g., trying to approve an already-approved draw).
• Suggestions are provided to resolve the issue via another API call or manual action through the Neighborly Portal.

---

Bulk Action Error Responses

For bulk endpoints, error handling works as follows:

• If the entire request is invalid (e.g., malformed body, invalid authentication), a standard error response is returned with a status code such as 400 or 401.
• If some items fail but others succeed, the API still returns a 200 OK status. The response body includes per-item statuses indicating which succeeded and which failed, along with detailed error messages and suggestions for the failed items.

---

Best Practices

• Always check the HTTP status code in the response.
• Use the message for general logging and user alerts.
• Refer to details and suggestion to inform users or debug the request.
• For 409 Conflict errors, determine if manual resolution in the Neighborly Portal is necessary.