Skip to content
/
Core Concepts

Core Concepts

This page summarizes the essential concepts, behaviors, and “gotchas” every developer should understand when integrating with the VBASoftware API (VBAPI). These guidelines help ensure stable, performant, and predictable integrations across all environments.

Authentication Basics

VBAPI uses a two-step authentication model:

  1. User Authentication — Exchange username/password credentials for an ID Token (JWT).
  2. Bearer Auth — Send the ID Token in the Authorization header for all API requests.

Required headers for every request:

x-api-key: YOUR_API_KEY
Authorization: Bearer <id_token>
vbasoftware-database: YOUR_DATABASE
User-Agent: <your-app-name>   # required

Why the User-Agent Header Matters

Always include a clear User-Agent string. VBA uses it for:

  • Request fingerprinting
  • Debugging
  • Identifying traffic patterns
  • Issue triage via Support

Failing to set a User-Agent will result in a 403 Forbidden response.

Rate Limits

VBAPI enforces throttling using a token bucket–style algorithm.

Default limits:

  • 25 requests per second sustained
  • 50 requests per second burst
  • Additional bursts allowed within the internal smoothing window

When limits are exceeded, VBAPI returns: 429 Too Many Requests

Increasing Limits

Clients may request a Service Level Review via VBA Support.

Approvals depend on:

  • Expected production load
  • Integration design
  • Test results in lower environments

Pagination Essentials

Most List endpoints support pagination with

Request Query parameters:

  • page
  • pageSize
  • sortBy

Response Header x-pagination:

  • TotalCount
  • TotalPages
  • CurrentPage
  • PageSize

Avoid requesting extremely large datasets in a single call.
Use paginated loops to prevent timeouts and throttling.

Timeouts & Retries

Recommended client behavior:

  • Timeout: 30 seconds
  • Retry policy: exponential backoff for 429, 502, 503, 504
  • Idempotency: Retry-safe for GET; exercise caution with POST/PUT unless explicitly allowed

Common Gotchas

Missing User-Agent

Causes failed requests.

Frequent Authentication

ID Tokens can be cached locally for up to one day. Over use of the login process may result in 429 responses.

No Pagination

Large unbounded requests may timeout. Use responsible page sizes for API traffic.

No Retry Logic

Transient 429 or 5xx errors must be handled gracefully by the client.

Previous page
Next page