Errors & Response Format
All responses share a common JSON envelope:
Success
json
{
"success": true,
"message": "Human-readable message",
"data": { }
}Error
json
{
"success": false,
"message": "Human-readable error description",
"data": null
}Validation error (422)
json
{
"success": false,
"message": "Validation failed.",
"data": {
"field_name": ["Error message"]
}
}HTTP status codes
| Status | Meaning |
|---|---|
| 200 | OK — successful GET, PATCH, or POST that doesn't create a resource |
| 201 | Created — resource successfully created |
| 400 | Bad Request — malformed request or a business-rule failure raised during processing |
| 401 | Unauthorized — missing or unrecognized API key |
| 403 | Forbidden — key valid but the account is inactive, unauthorized for this action, an inactive subscription, or an incomplete business profile (for example, no NRS Business ID or NRS Service ID yet) |
| 404 | Not Found — resource does not exist |
| 409 | Conflict — the resource is locked against the requested change (e.g. an invoice already processed by FIRS can no longer be edited) |
| 422 | Unprocessable Entity — request body failed validation |
| 500 | Internal Server Error |
Validation errors (422)
Requests validated by a Laravel Form Request use Laravel's standard validation error shape rather than the
envelope above — look for a top-level errors object, not data:
json
{
"message": "The invoice no field is required. (and 1 more error)",
"errors": {
"invoice_no": ["The invoice no field is required."],
"customer.email": ["The customer.email field must be a valid email address."]
}
}