Response HTTP Codes

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

Common uses found throughout VBAPI:

• 2xx: Success
  • 200 OK
  • 201 Created
• 4xx: Client Error
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
• 5xx: Server Error
  • 500 Internal Server Error

Response Payloads

All responses, regardless of success or error status, will have the same response envelope format. The top level components of the VBAPI response envelop are:

• data: Will be a JSON array if multiple items are returned (eg, a List operation) or a JSON object if a single item is returned (eg, a GET).
• error: Value is null if no error occurred. Will contain a JSON object if an error did occur.
• debug: Value is a JSON object containing an activityId. This id can be used to reference the request with customer support.

{
    "data": single object | array of objects | null on error,
    "error": single object | null,
    "debug": {
        "activityId": unique id of the request/response
    }
}

Data Object

A successful responses will contain a value for data (JSON Array | JSON Object), error will be null, debug will have a JSON Object.

{
    "data": [
     { ... }
    ],
    "error": null,
    "debug": {
        "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd"
    }
}

Error Object

An error responses will have a null value for data, error will be a JSON Object, debug will be a JSON Object. The error object contains 5 fields:

• type: a link describing the error message
• title: user-friendly title of the error
• status: the http error code, which matches the http response
• detail: contextual description of the error
• instance: the path called that triggered the error

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

Debug Object

Each API request/response is assigned a unique identifier called an activityId in the response debug object. The activityId links all of the system logs generated from a single request/response. If you need assistance about a specific request, providing the activityId will ensure the fastest possible resolution.