Errors & retries

Errors use RFC 9457 problem details with the media type application/problem+json. The code field is stable and machine-readable; title and detail are for humans and may change.

400 Bad Request

{
  "type": "https://developers.licenchain.io/api/docs/errors/#validation_failed",
  "title": "Request validation failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "One or more fields are invalid.",
  "traceId": "trc_4H8K2M6Q9R",
  "errors": [
    {
      "field": "price.netLicensedAmount",
      "code": "invalid_decimal",
      "message": "Use a decimal string with exactly two fraction digits, for example \"1200.00\"."
    }
  ]
}

Field	Description
type	URI identifying the error type.
title	Short human-readable summary.
status	HTTP status code.
code	Stable error code (see below).
detail	Human-readable explanation for this occurrence.
traceId	Quote this when contacting LicenChain support.
errors[]	Field-level problems for validation_failed: field, code, message.
existingRequestId	Present on duplicate_external_order.

Error bodies never contain API keys, onboarding links or Buyer personal data.

Error codes

Status	code	Endpoints	Retry?
400	validation_failed	Both	No — fix the request
401	unauthenticated	Both	No — fix or rotate the key
403	forbidden	Both	No
404	product_not_found	Licensing requests	No
404	licence_not_found	Verification	No — deny access
409	duplicate_external_order	Licensing requests	No — use existingRequestId
409	idempotency_key_reused	Licensing requests	No — use a new key only for a genuinely new order
429	rate_limited	Both	Yes, after Retry-After
503	service_unavailable	Both	Yes, with backoff

Retrying safely

• Licensing requests: retry network errors, timeouts, 429 and 503 with the same Idempotency-Key and the same body. You will either create the request once or receive the original result as an idempotent replay.
• Verification: retries are safe (read-only), but never grant new access while you are retrying.
• Honor Retry-After when present. Otherwise use exponential backoff with jitter (for example 1 s, 2 s, 4 s … capped at 60 s) and a bounded number of attempts.
• Do not retry 400, 401, 403, 404 or 409 unchanged — they will fail the same way.
• Set client timeouts (for example 10 s for licensing requests, 5 s for verification).

Rate limits

Requests are rate limited per API key. When you exceed the limit you receive 429 with Retry-After. Limits are set per Seller during onboarding.

429 Too Many Requests

{
  "type": "https://developers.licenchain.io/api/docs/errors/#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Retry after the number of seconds in the Retry-After header.",
  "traceId": "trc_4H8K2M6Q9R"
}