Errors and codes
Every error is a problem object as defined by RFC 9457 with a stable code. Check code, not the text.
The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Request-Id: req_8Kd2mVq7Xc1LpT4z
{
"type": "https://garanify.com/en/developers/errors/#validation_failed",
"title": "Request does not match the schema",
"status": 422,
"code": "validation_failed",
"detail": "The request body does not match the schema.",
"errors": [
{ "path": "/garan/years", "message": "must be multiple of 0.5" }
],
"requestId": "req_8Kd2mVq7Xc1LpT4z"
} typelinks to the entry below,titleis English and may change,detailexplains the case.errors[]comes withvalidation_failedand bulk upserts, with a JSON pointer inpath.requestIdmatches theRequest-Idheader. Quote it when you contact support. The SDKs put it inerror.requestId.- New codes may be added. Handle unknown codes by their HTTP status.
All codes
| Code | Status | Meaning | What to do |
|---|---|---|---|
missing_key | 401 | API key missing | Send Authorization: Bearer gfy_sk_…. |
invalid_key | 401 | API key invalid, expired or revoked | Check the key in your account; after a rotation use the new one. |
key_in_query | 400 | Secret keys are not allowed in the URL | Send secret keys only in the header. Revoke the key: it may now be in logs. |
secret_key_required | 403 | This endpoint needs a secret key | Publishable keys only read public data. Call the endpoint from your server. |
origin_not_allowed | 403 | Origin not allowed for this publishable key | The page is not on a domain of the shop. Add the domain with PATCH /v1/shops/{shop}. |
shop_not_found | 404 | Shop not found | The shop ID in the path does not match the key. |
product_not_found | 404 | Product not found | Register the product with PUT …/products/{sku}; URL-encode the SKU. |
key_not_found | 404 | Key not found | Use the key ID (key_…) from GET …/keys, not the secret. |
not_found | 404 | Resource not found | Check the path and the version (/v1). |
method_not_allowed | 405 | Method not allowed | Allowed methods are listed in the Allow header. |
invalid_json | 400 | Request body is not valid JSON | Send Content-Type: application/json and valid JSON. |
validation_failed | 422 | Request does not match the schema | errors[] lists every field with its path. |
payload_too_large | 413 | Request body too large | At most 256 KB, 4 MB for bulk upserts. |
plan_required | 403 | This feature needs Pro or Agency | Link a licence with PUT …/license. |
garan_limit_reached | 403 | Free plan limit for GARAN products reached | Existing labels stay visible. Link Pro for more products. |
idempotency_key_reused | 422 | Idempotency key was used with a different request | Use a new key for every new request. |
last_secret_key | 409 | The last active secret key cannot be revoked | Create a new secret key first, then revoke the old one. |
license_invalid | 422 | Licence key unknown or revoked | Copy the key again from your Garanify account. |
license_shop_limit | 409 | All shop slots of the licence are in use | Free a slot in your account or unlink another shop. |
account_shop_limit | 409 | The account has reached its maximum number of shops | Up to 100 shops per account; contact support for more. |
license_domain_locked | 409 | Primary domain is bound to the licence | Unlink the licence, change the domain, link it again. |
billing_unavailable | 503 | Licence service not reachable | Retry in a minute. Existing licences keep working. |
webhook_url_invalid | 422 | Webhook URL not allowed | Use HTTPS on a public host name. |
live_key_required | 403 | This endpoint needs a live key | Test shops have every feature without a licence. Link licences to live shops only. |
rate_limited | 429 | Too many requests | Retry after Retry-After seconds. |
internal_error | 500 | Internal error | Retry; if it persists, contact support with the time. |
Why no label?
A product without a label is not a request error. The resolution gives the reason in errors[].code:
| Code | Meaning |
|---|---|
years_missing | The producer guarantee in years is missing. |
years_too_low | GARAN only for producer guarantees of more than 2 years. |
years_not_half | Only whole or half years are allowed. |
years_implausible | The guarantee period is implausible (more than 99 years). |
brand_missing | The brand is missing: send brand or garan.brand. |
model_missing | The model identifier is missing: send mpn or garan.model. |