Errors

The GetQR API is in beta and is available to selected workspaces. Details may change before the general release.

The GetQR API uses standard HTTP status codes. Successful requests return 2xx. Failed requests return 4xx or 5xx with a JSON body that explains what went wrong.

Error format

Every error has the same shape: a stable code, a human-readable message and a link to that code’s description.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}

string

required

Stable, machine-readable error code. Use it in your code instead of the message. See Error codes.

string

required

Human-readable description of the problem. The wording can change.

string

required

Link to the description of the error code in the API documentation in your GetQR account.

Error codes

Code	HTTP status	When it happens
`bad_request`	400	The request is malformed: the body isn’t valid JSON, the `Authorization` header lacks the `Bearer` prefix, or the action isn’t allowed in the resource’s current state (for example, cancelling a finished bulk creation).
`unauthorized`	401	The API key is missing or invalid, for example because it was regenerated.
`forbidden`	403	The workspace owner’s subscription isn’t active, or your role in the workspace doesn’t allow this action.
`exceeded_limit`	403	You reached a plan limit. On the Single QR plan, creating or duplicating a QR code when the workspace already has one, or starting a bulk creation.
`not_found`	404	The resource doesn’t exist or isn’t in your workspace, the endpoint doesn’t exist, or the API isn’t enabled for your workspace.
`method_not_allowed`	405	The endpoint exists but doesn’t accept this HTTP method. The `Allow` header lists the methods it accepts.
`conflict`	409	The request clashes with existing data: the short link slug is taken, a request with the same `Idempotency-Key` is still in progress, a schedule overlaps an existing one, or a bulk archive isn’t ready yet.
`invite_pending`	409	You were invited to the workspace but haven’t joined yet. API key requests don’t return it: the key’s workspace is always one you belong to.
`invite_expired`	410	Your invite to the workspace has expired. API key requests don’t return it, for the same reason.
`unprocessable_entity`	422	The body or query parameters failed validation. The message names the field and what’s wrong with it. See Validation errors.
`rate_limit_exceeded`	429	The API key has used up its requests for the current window. See Rate limits.
`internal_server_error`	500	Something went wrong on our side. Retry later, and contact support if it keeps happening.

Validation errors

When the body or query parameters fail validation, the API answers 422. The message describes the first invalid field as <issue>: <field>: <details>:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}

Nested fields use dot notation, for example link.url.

Handle errors

Branch on error.code, not on error.message.
Don’t retry 4xx errors unchanged: fix the request first. The exceptions are a 409 for a request still in progress and 429.
On 429, wait for the number of seconds in the Retry-After header. See Rate limits.
Retry 5xx errors with exponential backoff.

Common issues

Every request returns 404 "This endpoint is not available."

The API is in beta and isn’t enabled for your workspace yet.

404 "This endpoint does not exist."

The path is wrong. Check it against the endpoint pages, and that it starts with /api/v1/.

403 "Access denied: This account does not have an active subscription."

The workspace owner’s subscription has ended. The API key works again as soon as the owner resubscribes.

403 "API access is not available for this role."

Your role in the workspace is viewer. Only the workspace owner and editors can use the API.

API

Error format

Error codes

Validation errors

Handle errors

Common issues

What’s next

Rate limits

Authentication

​Error format

​Error codes

​Validation errors

​Handle errors

​Common issues

​What’s next

Rate limits

Authentication

Error format

Error codes

Validation errors

Handle errors

Common issues

What’s next