# 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:**


```http
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.