API Response Handling

HTTP Response Codes

VBAPI adheres to conventional HTTP response codes to indicate the success or failure of an API request.

Success Responses (2xx)

  • 200 OK – The request was successful, and the response contains the requested data.
  • 201 Created – The request successfully created a resource.

Client Errors (4xx)

  • 400 Bad Request – The request was malformed or invalid.
  • 401 Unauthorized – Authentication is required or failed.
  • 403 Forbidden – The authenticated user lacks necessary permissions.
  • 404 Not Found – The requested resource does not exist.

Server Errors (5xx)

  • 500 Internal Server Error – A generic server error occurred.

Response Payload Structure

Every response from VBAPI follows a standardized envelope format, ensuring consistency across successful and error responses.

Copy
Copied
{
    "data": single object | array of objects | null on error,
    "error": single object | null,
    "debug": {
        "activityId": "unique request identifier"
    }
}

Data Object

Successful responses include a data field, which contains either a single object or an array of objects. The error field remains null, and the debug object contains an activityId.

Example:

Copy
Copied
{
    "data": [
        { "id": 1, "name": "Example" }
    ],
    "error": null,
    "debug": {
        "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd"
    }
}

Error Object

If an error occurs, the data field is null, and an error object provides details. The debug object still contains an activityId.

Error Object Fields:

  • type – A URL linking to additional information about the error.
  • title – A brief, user-friendly summary of the error.
  • status – The HTTP status code corresponding to the error.
  • detail – A descriptive message explaining the error.
  • instance – The specific API endpoint where the error occurred.

Example:

Copy
Copied
{
    "data": null,
    "error": {
        "type": "https://httpstatuses.com/404",
        "title": "Not Found",
        "status": 404,
        "detail": "The requested resource (xyz) was not found.",
        "instance": "/clients/abc/products/xyz"
    },
    "debug": {
        "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd"
    }
}

Debug Object

Each response includes a debug object containing a unique activityId. This identifier links all internal logs related to a specific request. When seeking support, providing the activityId ensures the fastest resolution.

By structuring responses in this format, VBAPI ensures consistency, traceability, and ease of troubleshooting for developers.