Response and Error Handling

Proper response and error handling ensures that NSPS connectors provide clear feedback for every event, maintain a complete audit trail, and allow programmatic handling of failures. The connector must always send a response back to NSPS after processing each event, regardless of success or error.

This ensures:

• Event Acknowledgment: NSPS knows that the event has been received and processed.
• Audit Trail Completeness: All responses, including success and error messages, are stored in the Event History database, providing a complete audit trail accessible via the Management UI.
• Error Visibility: Sending detailed error responses helps NSPS track issues and aids in debugging and programmatic handling.

Error Response Structure

All error responses must follow the ErrorResponse schema:

{
    "message": "Detailed description of the error",
    "error": "Specific failure reason",
    "type": "ERROR_TYPE",
    "details": "Optional additional details for validation or internal errors"
}

Error Response Fields:

• message: General description of the operation result (also used in successful responses).
• error: Detailed error description, indicates the specific reason for processing failure.
• type: Error type for programmatic handling. Examples:

  "VALIDATION_ERROR"
  "AUTHENTICATION_ERROR"
  "SERVICE_ERROR"
  "CONNECTION_ERROR"
  "RATE_LIMIT_ERROR"
  "INTERNAL_ERROR"
  

• details: Additional details, such as a list of validation errors or a stack trace for internal errors (optional).

Standard Response Examples

All response codes, messages, and error details are stored in the Event History database and are available for analysis via the Management UI.

202 Accepted – Event accepted for processing:

{
    "message": "Event accepted for processing"
}

401 Unauthorized – Invalid access token:

{
    "message": "Invalid access token",
    "error": "Unauthorized",
    "type": "AUTHENTICATION_ERROR"
}

See also the Authorization section.

404 Not Found – Resource not found:

{
    "message": "Resource not found",
    "error": "Not found",
    "type": "VALIDATION_ERROR"
}

405 Method Not Allowed – HTTP method not supported:

{
    "message": "Method not allowed",
    "error": "Method not allowed",
    "type": "VALIDATION_ERROR"
}

422 Unprocessable Entity – Validation failed:

{
    "message": "Validation failed",
    "error": "Validation failed",
    "type": "VALIDATION_ERROR",
    "details": [
        {
            "loc": ["body", "data", "event_type"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

See also the Input Validation section.

429 Too Many Requests – Rate limit exceeded:

{
    "message": "Too many requests to API Core",
    "error": "Rate limit exceeded",
    "type": "RATE_LIMIT_ERROR"
}

500 Internal Server Error – API or service error:

{
    "message": "API Core HTTP error",
    "error": "Internal server error",
    "type": "SERVICE_ERROR"
}

503 Service Unavailable – Core service is not available:

{
    "message": "Core service is not available",
    "error": "Connection timeout",
    "type": "CONNECTION_ERROR"
}