Skip to main content

Error Handling

This service uses consistent error handling patterns for all API endpoints. Errors are returned as JSON objects with a statusCode, message, and error field.

Common Error Types​

  • 400 Bad Request: Invalid input, missing required fields, or failed validation.
  • 404 Not Found: Resource does not exist.
  • 409 Conflict: Duplicate resource (e.g., externalId already exists).
  • 500 Internal Server Error: Unexpected server error.

Example Error Response​

{
  "statusCode": 400,
  "error": ["id must be a UUID"],
  "requestId": "72e32108-6260-45e9-bb12-325fe3b61e42",
  "path": "/accounts/invalid-id",
  "timestamp": "2025-11-19T16:32:57.915Z"
}

Validation​

All DTOs are validated using NestJS's ValidationPipe. Invalid requests are rejected with detailed error messages.

Handling Duplicate externalId​

When creating accounts or customers, if the externalId already exists, a 409 Conflict error is returned.

Error Mapping​

SDK and database errors are mapped to appropriate HTTP status codes and messages.