Barcode Labels Docs

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

HTTPCodeMeaning
400missing_paramA required parameter is absent
400invalid_type, invalid_format, invalid_size, invalid_orientation, invalid_scale, invalid_height, invalid_rotate, invalid_includetext, invalid_showtext, invalid_textA parameter has an invalid value; the message lists valid values
401invalid_api_keyThe Authorization header is malformed, or the key is unknown or revoked
403invalid_signatureA signed link (from the MCP server) was altered
422encode_failedThe value can't be encoded in the chosen symbology (e.g. wrong check digit, invalid characters) — the message includes details
429rate_limitedPer-minute request limit exceeded — retry after the Retry-After seconds
429quota_exceededLabel allowance used up. Daily allowances reset at UTC midnight (Retry-After is set); otherwise buy a pack or upgrade
500internal_errorServer-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.

PlanPriceLabelsRequests/minuteKeys
No keyFree300 per day, per IP10—
Free$0500 per day601
Label pack$10 one-time10,000, valid 12 months, packs stack1,0005
Starter$14.99/month50,000 per billing period1,0005
Pro$50/month1,000,000 per billing period1,0005

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 minute
  • X-RateLimit-Remaining — remaining burst capacity
  • X-RateLimit-Reset — seconds until the bucket fully refills
  • X-Quota-Remaining — labels left across your allowances after this request
  • Retry-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.

On this page