API Request and Response Format

Request format

All request bodies must be Content-Type: application/json. Example:

POST /api/v1/clients
Content-Type: application/json

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Ltd"
}

Success response

{
  "success": true,
  "data": { ... },
  "message": "Client created"
}

Paginated response

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3
  }
}

Error response

{
  "success": false,
  "error": {
    "message": "Client not found",
    "code": "NOT_FOUND",
    "errors": []
  }
}

Query parameters

List endpoints support: ?page=1, ?per_page=50 (max 100), ?search=..., ?status=..., ?client_id=... (where applicable).

Error codes

Rate limit headers and retry

When rate limited (429), implement exponential backoff. Wait 60 seconds before retrying, or longer if you receive 429 repeatedly. The limit is 100 requests per 60-second window per endpoint per API key.

Idempotency (payments/invoices)

POST /api/v1/invoices/{id}/pay is not idempotent: calling it twice will record two payments. Ensure your integration does not double-submit. For POST /api/v1/clients, duplicate emails return EMAIL_EXISTS (400).