Handling Errors

Overview

The Nxsys API uses standard HTTP response codes to indicate the success or failure of requests, complemented by a consistent JSON error response format for detailed feedback. To ensure a robust integration with Nxsys, it’s essential to write code that gracefully handles exceptions caused by issues such as failed transactions, invalid parameters, authentication failures, or network unavailability.

HTTP Status Codes

The Nxsys API employs standard HTTP status codes to provide clear feedback on the outcome of your requests, enabling efficient diagnosis and resolution of issues.

Status Code	Description
`200`	OK: The request was successful.
`201`	Created: The resource was successfully created (e.g., a new record).
`400`	Bad Request: The request is invalid or cannot be processed due to malformed input.
`401`	Unauthorized: Authentication credentials are missing or invalid.
`403`	Forbidden: The authenticated user lacks permission to access the requested resource.
`404`	Not Found: The requested resource does not exist in Nxsys.
`422`	Unprocessable Entity: The request is well-formed but contains semantic errors (e.g., invalid data format).
`429`	Too Many Requests: The API rate limit has been exceeded.
`500`	Internal Server Error: An unexpected issue occurred on the Nxsys API servers.

Error Response Format

When an error occurs, the Nxsys API returns a JSON response with a consistent structure to facilitate troubleshooting and error handling:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {
      // Optional: Additional context or specific error information
    }
  }
}

Example Error Response

{
  "error": {
    "code": "invalid_parameter",
    "message": "The provided ID format is invalid",
    "details": {
      "field": "id",
      "expected_format": "XX-999999999"
    }
  }
}

Common Error Codes

The following error codes are commonly encountered when interacting with the Nxsys API. Use these to implement targeted error-handling logic in your application.

Authentication Errors

invalid_credentials: The API key is invalid or has expired.

missing_credentials: No API key was provided in the request.

insufficient_permissions: The API key lacks the necessary permissions to access the requested resource.

Validation Errors

invalid_request: The request payload is malformed or missing required fields.

invalid_parameter: One or more parameters are invalid (e.g., incorrect ID format).

resource_not_found: The requested resource does not exist in Nxsys.

Best Practices for Error Handling

To ensure a resilient and user-friendly integration with the Nxsys API, follow these recommendations:

Validate Inputs: Verify request data before submission to prevent 400 or 422 errors, especially for critical fields like IDs or amounts.

Handle Specific Error Codes: Use the error.code field to implement logic for specific scenarios, such as prompting re-authentication for 401 errors.

Implement Retry Logic: For transient errors like 429 (rate limit exceeded) or network issues, use exponential backoff to retry requests responsibly.

Log Errors Effectively: Capture error.message and error.details for debugging and monitoring to streamline troubleshooting.

Provide User-Friendly Feedback: Translate technical errors into clear, non-technical messages for end-users (e.g., "Invalid ID provided" instead of exposing raw API errors).

Example Error Handling

Below is an example of handling Nxsys API errors in JavaScript/Node.js, demonstrating how to parse error responses and manage exceptions gracefully:

Overview#

HTTP Status Codes#

Error Response Format#

Example Error Response#

Common Error Codes#

Authentication Errors#

Validation Errors#

Best Practices for Error Handling#

Example Error Handling#