Support and escalation

This page is for developers who have hit a VBAPI problem they cannot solve from the documentation. It explains what to collect before you contact VBA, how to find the activityID that lets VBA find your request in its logs, and where to get in touch.

Many problems have a known cause. Check these first:

• The AI assistant: select the chat button on any page to ask about these docs. See AI and MCP.
• FAQ, which starts with the most common first-call errors.
• Errors and troubleshooting, for what each status code means and what to do.
• Rate limits and performance, if you are getting 429.

Also include:

• the HTTP status code you received
• the database you called, which is the value of your vbasoftware-database header
• whether the problem happens every time or only sometimes, and when it started
• for a workflow problem, the IDs of the records involved (for example the subscriber_ID or auth_Number) rather than names or other personal details

Never send your password, API key, ID token, or real member data such as names, birth dates, or Social Security numbers.

Every JSON response has the same envelope, and debug.activityID identifies the request in VBA's logs:

JSON responses are wrapped in the same envelope:

{
  "data": { },
  "error": null,
  "debug": { "activityID": "00000000-0000-0000-0000-000000000000" }
}

• data holds the result: one object for a get, create, or update, and an array for a list.
• error is null on success. On failure it is a problem-details object with type, title, status, detail, and instance.
• debug.activityID identifies the request in VBA's logs. Successful responses spell it activityID; error responses spell it ActivityID, so read the property without regard to case (the sample clients do). Log it with every failure and include it when you contact support.

Not every response has an envelope. 204 No Content (deletes) has no body, some 202 Accepted responses for queued work return only a short confirmation message, and the API gateway answers 401 with {"message":"Unauthorized"} and 403 with {"message":"Forbidden"}.

How to get it:

• From a response: read debug.activityID from the body. The name is activityID, with a capital ID; activityId does not exist.
• From the documentation samples: the shared helpers put it on their error types, as VbapiException.ActivityId in C#, VbapiError.activity_id in Python, and VbapiError.activityId in TypeScript, and include it in the error message. Successful responses expose it as ActivityId, activity_id, or activityId.
• In your own code: log debug.activityID with the method, path, status code, and time of every failed call, so you have it when you need it.

Some responses have no body, and so no activityID: 204 No Content from a delete, some 202 Accepted responses for queued work that return only a short message, and 401 Unauthorized. For these, send the time of the call (with time zone), the method and path, and the status code.

API keys, client IDs, client codes, database names, and API users are issued by VBA. To get new ones, replace a compromised key, or add a database, ask your VBA Account Executive (see Contact VBA). See Credentials and environments for what each credential is.

The limit is 25 requests per second sustained, with bursts up to 50, per API key. If your integration needs more, ask VBA through one of the channels in Contact VBA and describe the workload: which operations, how many requests, and at what times. Before you ask, check the advice in Rate limits and performance.

• FAQ
• Errors and troubleshooting
• Requests and responses