Standardized Error Codes in fabric

fabric uses a standardized error-handling framework. This framework is designed to make understanding and troubleshooting errors much simpler and more consistent across all our systems, allowing you to quickly pinpoint what went wrong, where it happened, and how to fix it.

​

How it works

This standardized error-handling framework uses two main components:

Standardized Error Codes: fabric maintains a shared set of codes for common scenarios that can occur across services. This means if you see SERVICE-4002 for an Invalid value error, you know what that error means, regardless of which service returned it.

Structured JSON Error Responses: All API errors come in a consistent JSON format. This format is crucial because it consolidates all relevant details in one place.

​

Error format example

Every time an API error occurs, you’ll receive a JSON object that looks like this:

{
  "type": "CLIENT_ERROR",
  "errorCode": "SERVICE-4006",
  "message": "This record has been modified by another request, please resubmit.",
  "context": {
    "service": "allocations",
    "endpoint": "PUT /v3/allocations/allocation-request-id/1000667280"
  }
}

• type: Provides the category of the error such as CLIENT_ERROR if it’s something wrong with your request.
• errorCode: Provides a specific, standardized code such as SERVICE-4006 that tells you exactly what kind of error occurred.
• message: A human-readable explanation of the error.
• context: An object used for debugging. The context object tells you which service encountered the error and the specific API endpoint that triggered the error. This helps you trace the problem back to its source.

Sometimes, especially with validation, a single request might have several problems. In these cases, the framework supports returning an array of errors:

{
    "type": "CLIENT_ERROR",
    "errorCode": "SERVICE-4007",
    "message": "Multiple field(s) are invalid/missing",
    "errors": [
        {
            "type": "CLIENT_ERROR",
            "errorCode": "SERVICE-4000",
            "message": "'orderNumber' can't be null"
        },
        {
            "type": "CLIENT_ERROR",
            "errorCode": "SERVICE-4000",
            "message": "items must be added to the request payload!"
        }
    ],
    "context": {
        "service": "orders",
        "endpoint": "POST /v3/orders"
    }
}

​

Understanding Error Code Definitions

fabric’s standardized error codes fall into two main categories:

Generic Service Errors: These are universal, reusable codes for common API and service-level issues that can happen in any part of the fabric system. Think of these as standard problems such as “invalid input” or “resource not found.”

Module-Specific Errors: These codes are unique to a particular service and reflect specific business logic issues. For example, an order service might have an error code for “insufficient stock” that wouldn’t apply to an allocation service.

By separating these, you can quickly identify whether an error is a general API misuse or something specific to the business rules of the service you’re interacting with.