API errors
Errors and Data Safety
Handle validation, authentication and resource errors with stable JSON responses.
JSON errorsSafe responsesScoped access
Standard error response
{
"success": false,
"error": {
"code": "validation_failed",
"message": "The amount field is required.",
"details": {
"amount": [
"The amount field is required."
]
}
}
}Common error codes
| Code | When it happens | How to fix it |
|---|---|---|
authentication_failed | The bearer secret key is missing, incorrect or disabled. | Check the Authorization header and use a server-side secret key. |
invalid_signature | A signed write request has a missing or invalid timestamp/signature. | Generate the HMAC signature from timestamp + "." + rawBody. |
validation_failed | A required field is missing or a value is not valid. | Check the endpoint parameter table and send JSON with the correct types. |
resource_not_found | The id does not exist for the authenticated merchant or selected connected account. | Confirm the id and, for NeroConnect, the NeroPay-Account header. |
idempotency_conflict | The same idempotency key was reused with a different body. | Retry with the same request body or create a new idempotency key. |
account_not_found | The selected connected account is not assigned to the platform. | Use a valid public connected account id such as NPxxxx_12345. |
Safe data handling
NeroPay API responses are designed for integration, reconciliation and display. Sensitive payment, banking, security, compliance and operational data is protected and should not be requested or sent unless an endpoint explicitly requires it.
Validation errors
When a field is invalid, the API returns validation_failed with an optional details object. Developers should display a friendly message to staff or customers and log the error code for support.
{
"success": false,
"error": {
"code": "validation_failed",
"message": "The currency field must be GBP, EUR or USD.",
"details": {
"currency": [
"The selected currency is invalid."
]
}
}
}