API Authentication and Rate Limits: Tokens, OAuth and Errors

Authenticate with a personal access token or OAuth 2.0 in the Authorization header; stay under 60 requests a minute and handle 401, 422, 426, and 429 responses.

Prerequisites

• Plan: Individual Plan ($19 one-time) or Agency Plan ($49 one-time) - not the Free Plan
• API Settings: Settings → Integrations → Manage API Keys
• Reference: the public API docs at breezedoc.com/developer/docs

Which Authentication Method Should I Use?

Both send the token the same way. Step-by-step setup: Personal Access Tokens and How to Set Up an OAuth 2.0 Client for Your App.

How Do I Send the Token?

Add the token to the Authorization header of every request:

curl -X GET https://breezedoc.com/api/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

• The personal access token is shown once, when you create it - store it in an environment variable or secrets manager.
• To revoke a token, click Delete next to it on API Settings. Requests with it then return 401.
• OAuth apps use the authorization code flow: https://breezedoc.com/oauth/authorize and https://breezedoc.com/oauth/token. The Client ID and Secret stay visible in the OAuth Clients table.

What Are the Rate Limits?

• Every endpoint: 60 requests per minute per account.
• Creating documents (POST /api/documents, POST /api/templates/{id}/create-document): 100 per day.
• Sending documents (POST /api/documents/{id}/send): 20 per hour.
• Creating invoices (POST /api/invoices): 100 per day.
• Sending invoices: 20 per hour - POST /api/invoices/{id}/send, plus POST /api/invoices and PUT /api/invoices/{id} unless the request includes "send": false.

Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. A 429 response adds Retry-After (seconds to wait). Read requests are only subject to the per-minute limit, so polling is safe.

What Do the Error Responses Mean?

Errors are JSON with a message. Validation errors look like this:

{
  "message": "The customer email field is required.",
  "errors": {
    "customer_email": ["The customer email field is required."]
  }
}

Best Practices

• Keep tokens on the server - never in browser code or a public repository.
• Use a separate token per environment and delete tokens you no longer need.
• Retry 429 and 5xx responses with backoff; do not retry 4xx validation errors unchanged.
• Poll GET /api/documents/{id}/recipients for status - there are no webhooks.
• Replace personal access tokens before they turn one year old.

Endpoints and workflows are listed in BreezeDoc API: Getting Started.

Troubleshooting

Every request returns 401 "Unauthenticated."

• Check the header format: Authorization: Bearer YOUR_TOKEN.
• The token may have been deleted or be over one year old - create a new one.

I get 401 with a token from the client credentials grant

• Client credentials tokens belong to no user, so every /api/ endpoint rejects them. Use a personal access token, or the authorization code flow so the token acts for a user.

Sending returns 426

• The account's monthly sending allowance is used up. It resets on the 1st of the month; see How to Upgrade.

I keep getting 429

• You hit the per-minute limit or a daily/hourly cap on creating or sending. Wait for Retry-After and spread the requests out.

Still stuck? Email support@breezedoc.com with the endpoint, the status code, and the response body (never your token).

Frequently Asked Questions

Do API tokens expire?

Yes. Personal access tokens and OAuth access tokens expire after one year.

How many requests can I make per day?

Reads are limited only to 60 per minute. Creating documents or invoices is capped at 100 per day, and sending at 20 per hour.

Does BreezeDoc support webhooks?

No. Poll the documents or recipients endpoints for status changes.

Can I regenerate a token?

No. Delete it on API Settings and create a new one, then update your application.

Need more help? Contact our support team at support@breezedoc.com - we are here to help!