Hoppa till innehållet
Garanify

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"
}
  • type links to the entry below, title is English and may change, detail explains the case.
  • errors[] comes with validation_failed and bulk upserts, with a JSON pointer in path.
  • requestId matches the Request-Id header. Quote it when you contact support. The SDKs put it in error.requestId.
  • New codes may be added. Handle unknown codes by their HTTP status.

All codes

CodeStatusMeaningWhat 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:

CodeMeaning
years_missingThe producer guarantee in years is missing.
years_too_lowGARAN only for producer guarantees of more than 2 years.
years_not_halfOnly whole or half years are allowed.
years_implausibleThe guarantee period is implausible (more than 99 years).
brand_missingThe brand is missing: send brand or garan.brand.
model_missingThe model identifier is missing: send mpn or garan.model.