Error Handling

Application Response Codes

These are the core response codes used throughout the ERM system for business logic errors.

Error Types

The ERM system uses typed errors to categorize different failure modes.

1. AppErrorFormat

HTTP Status: 400 Bad Request

A structured application error with code, details, and description.

{
  "error": "sender-gateway-not-found",
  "code": "92",
  "description": "Issue/Error with routing configuration for the receiving institution"
}

2. ErrorMissingParameter

HTTP Status: 400 Bad Request

Occurs when a required parameter is not provided.

{
  "error": "error-missing-parameter",
  "data": "parameter_name",
  "message": "Missing Required Parameter",
  "code": "optional_code"
}

Possible Actions:

• Check API documentation for required fields
• Ensure all mandatory parameters are included in the request

3. ErrorNotFound

HTTP Status: 404 Not Found

Resource not found in the system.

{
  "error": "error-not-found",
  "data": "resource_id",
  "message": "Not Found"
}

Possible Actions:

• Verify the resource ID is correct
• Check if the resource was created
• Ensure you have permission to access the resource

4. ErrorInvalidJSON

HTTP Status: 400 Bad Request

Request body is not valid JSON.

{
  "error": "error-invalid-json",
  "data": null,
  "message": "The JSON data you submitted is not well formed JSON!"
}

Possible Actions:

• Validate JSON syntax before sending
• Check for missing brackets, quotes, or commas
• Use a JSON validator tool

5. ErrorInvalidIdentifierFormat

HTTP Status: 400 Bad Request

Identifier contains invalid characters.

{
  "error": "error-invalid-identifier-format",
  "data": "parameter_name",
  "message": "Invalid Identifier Format. Only letters a-z, digits 0-9, and characters [_-.@#&+%] are valid."
}

Possible Actions:

• Remove special characters not in the allowed set
• Use URL encoding if necessary
• Validate identifiers before submission

6. ErrorInvalidEmailFormat

HTTP Status: 400 Bad Request

Email address is not in valid format.

{
  "error": "error-invalid-email-format",
  "data": "email_parameter",
  "message": "error-invalid-email-format"
}

Possible Actions:

• Verify email follows standard format ([email protected])
• Check for typos in the email address

7. ErrorInvalidNumber

HTTP Status: 400 Bad Request

Numeric field contains invalid value.

{
  "error": "error-invalid-number",
  "data": "parameter_name",
  "message": "error-invalid-number"
}

Possible Actions:

• Ensure the value is numeric
• Check decimal separator (use period, not comma)
• Verify the number is within an acceptable range

8. ErrorWrongFormat

HTTP Status: 400 Bad Request

Data format doesn't match the expected format.

{
  "error": "error-wrong-format",
  "data": "parameter_name",
  "message": "Wrong Format: details"
}

Possible Actions:

• Review API documentation for the expected format
• Check date formats (ISO 8601 recommended)
• Verify currency codes are ISO 4217 compliant

9. ErrorIncompleteData

HTTP Status: 422 Unprocessable Entity

The request is valid, but the data is incomplete for processing.

{
  "error": "error-incomplete-data",
  "details": "specific_details",
  "extra": {}
}

Possible Actions:

• Review the details field for specific missing information
• Complete all required data fields
• Check for dependent field requirements

10. ErrorConflictOperationAlreadyPerformed

HTTP Status: 409 Conflict

Attempting to perform an operation that was already completed.

{
  "error": "error-conflict-operation-already-performed",
  "data": "operation_id",
  "message": "error-conflict-operation-already-performed; status:id"
}

Possible Actions:

• Check the current status of the resource
• Do not retry idempotent operations that succeeded
• Use GET to retrieve the current state

11. ErrorEncryption

HTTP Status: 500 Internal Server Error

Encryption/decryption operation failed.

{
  "error": "error-encryption",
  "data": "",
  "message": "error-encryption: extra_info"
}

Possible Actions:

• Verify encryption keys are configured correctly
• Check that the encryption algorithm matches the expected
• Contact the system administrator

HTTP Status Codes

Detailed Error Messages

Payment Processing Errors

Account Verification Errors

Authentication & Signature Errors

Configuration Errors

Recall Payment Errors

Error Response Format

Standard Error Response

{
  "error": "error-type-identifier",
  "code": "numeric_code",
  "description": "Human-readable description",
  "data": "additional_context",
  "message": "Detailed message"
}

AppErrorFormat Response

{
  "error": "specific-error-detail",
  "code": "XX",
  "description": "Standard description for code XX"
}