HCC2D API

The HCC2D REST API lets you generate HCC2D and QR codes programmatically. Access requires an API key — request one here.

Authentication

Pass your key in the Authorization header:

Authorization: Bearer hcc2d_<64 hex chars>

Requests without a valid key are rejected with HTTP 401.

Base URL

https://hcc2d.com/api/v1

Endpoints

POST /api/v1/generate

Encode a payload into an HCC2D or QR code and receive a PNG image.

Request body (JSON)

Field	Type	Required	Description
`payloadBase64`	`string`	yes	Base64-encoded payload bytes
`inputName`	`string`	no	Filename stored inside the HCC2DF container (for example payload.txt or data.pdf). Defaults to payload.bin. Ignored when structured: false.
`structured`	`boolean`	no	Wrap the payload in the HCC2DF container (filename + zlib compression). Defaults to true. Set false to store raw bytes without a container. Use false for URL and vCard payloads so the decoder can recognise the content directly. See the HCC2DF format reference.
`mode`	`string`	no	Symbol type: qr, hcc2d4 (4-colour), hcc2d8 (8-colour, default)
`ec`	`string`	no	Error-correction level: L, M, Q, H (default M)
`version`	`integer`	no	Symbol version (1–40). Use 0 for auto-selection (default).
`scale`	`integer`	no	Pixels per module (1–64, default 12)
`quietZone`	`integer`	no	Quiet-zone width in modules (0–64, default 4)

Example request

curl -X POST https://hcc2d.com/api/v1/generate   -H "Authorization: Bearer hcc2d_<your-key>"   -H "Content-Type: application/json"   -d '{
    "payloadBase64": "SGVsbG8sIFdvcmxkIQ==",
    "inputName": "payload.txt",
    "structured": true,
    "mode": "hcc2d8",
    "ec": "M",
    "version": 0,
    "scale": 4,
    "quietZone": 4
  }' --output code.png

Success response (200)

{
  "ok": true,
  "imageUrl": "/generated/<uuid>.png",
  "message": "Code generated successfully — Version 1"
}

Error response

{
  "ok": false,
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

Error codes

HTTP	Code	Meaning
400	`missing_payload`	payloadBase64 is absent or empty
400	`invalid_base64`	payloadBase64 is not valid base64
400	`empty_payload`	Decoded payload is zero bytes
400	`payload_over_max`	Decoded payload exceeds the server pre-encode limit (65,536 bytes by default)
400	`too_large_settings`	Payload fits globally but not with the requested version/EC/mode combination
400	`too_large_absolute`	Payload exceeds what any symbol can hold even at maximum capacity (HCC2D8, version 40, EC level L, about 8,859 bytes). Reduce the payload size.
400	`encoder_failed`	Encoder rejected the input for a reason other than capacity
400	`invalid_mode / invalid_ec / invalid_version / invalid_scale / invalid_quiet_zone`	A request field is outside its allowed range
401	`auth_required`	Missing, invalid, or revoked API key
413	`body_too_large`	HTTP request body exceeds the body-parser limit (about 86 KB). In practice this means the payload is too large.
415	`unsupported_media_type`	Content-Type is not application/json
429	`rate_limited`	Per-key or per-IP request rate limit reached
429	`too_many_jobs`	Server is at the concurrent encoder-job limit; retry after a short delay
500	`internal_error`	Unexpected server-side failure
502	`missing_output`	Encoder ran but produced no output image
503	`encoder_unavailable`	Encoder binary is missing on the server
504	`encoder_timeout`	Encoder process exceeded the timeout (default 30 s)

Rate limits

Limit	Value
Per API key	30 requests / minute
Per IP (with key)	60 requests / minute
Brute-force lockout	10 failed auth attempts / 15 min locks the IP for 15 min

When a limit is hit the server returns 429 with a Retry-After header.

Need higher limits? Write to info@hcc2d.com.

Payload size limits

Layer	Limit	Enforced by
Body parser	~86 KB (auto-derived)	Server, before JSON parsing — returns body_too_large
Pre-encode check	65,536 bytes (64 KB)	Server, after decoding base64 — returns payload_over_max
Absolute barcode maximum	~8,859 bytes	Encoder — returns too_large_absolute
Settings-specific	Depends on version + EC level	Encoder — returns too_large_settings

By default the server applies zlib compression through the HCC2DF container before encoding, so raw inputs up to 64 KB can often still fit. Pass structured: false to skip the container and encode raw bytes.

The web UI also applies a client-side upload limit of 64 KB, aligned with the server pre-check.

Image retrieval

Generated PNGs are served at https://hcc2d.com<imageUrl> and are retained for 1 hour. Download them promptly after generation.

Get an API key

Request an API key from the official form.