Errors & Rate Limits
Error format, error codes, plans, and rate limits.
Error format
All errors are JSON:
{ "error": { "code": "invalid_type", "message": "Invalid or missing type. Valid types: ..." } }Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | missing_param | A required parameter is absent |
| 400 | invalid_type, invalid_format, invalid_size, invalid_orientation, invalid_scale, invalid_height, invalid_rotate, invalid_includetext, invalid_showtext, invalid_text | A parameter has an invalid value; the message lists valid values |
| 401 | invalid_api_key | The Authorization header is malformed, or the key is unknown or revoked |
| 403 | invalid_signature | A signed link (from the MCP server) was altered |
| 422 | encode_failed | The value can't be encoded in the chosen symbology (e.g. wrong check digit, invalid characters) — the message includes details |
| 429 | rate_limited | Per-minute request limit exceeded — retry after the Retry-After seconds |
| 429 | quota_exceeded | Label allowance used up. Daily allowances reset at UTC midnight (Retry-After is set); otherwise buy a pack or upgrade |
| 500 | internal_error | Server-side rendering failure — barcode or label rendering failed, PDF assembly failed, or label rendering is temporarily unavailable. Not caused by request parameters; safe to retry. |
Plans and limits
Usage is counted in labels: a /api/v1/label or /api/v1/design PDF with qty=N counts N labels, and a /api/v1/templates/{id}/render PDF counts one per page; every other successful request (a barcode image, a label PNG, the legacy route counts qty) counts 1. Requests that fail validation or rendering are not counted.
| Plan | Price | Labels | Requests/minute | Keys |
|---|---|---|---|---|
| No key | Free | 300 per day, per IP | 10 | — |
| Free | $0 | 500 per day | 60 | 1 |
| Label pack | $10 one-time | 10,000, valid 12 months, packs stack | 1,000 | 5 |
| Starter | $14.99/month | 50,000 per billing period | 1,000 | 5 |
| Pro | $50/month | 1,000,000 per billing period | 1,000 | 5 |
Every signed-in account keeps the free 500 labels/day. Labels are drawn from the free daily allowance first, then the subscription's monthly allowance, then label packs (soonest-expiring first). Monthly allowances reset on the billing date and do not roll over. All keys on an account share its allowance.
Buy packs and manage subscriptions at barcodelabels.io/account.
Response headers
X-RateLimit-Limit— requests allowed per minuteX-RateLimit-Remaining— remaining burst capacityX-RateLimit-Reset— seconds until the bucket fully refillsX-Quota-Remaining— labels left across your allowances after this requestRetry-After— on 429 responses, seconds until a retry can succeed (omitted when only a purchase helps)
Keyed responses are sent with Cache-Control: private, so shared caches never store them.