Skip to Content
PortcullisDocs
Reference

Error codes

Stable client API error codes, their HTTP status and how products should handle them.

Client API errors use this envelope. The code values are stable and part of the public contract.

{
  "status": "error",
  "data": { "message": "Human-readable message", "code": "MACHINE_LIMIT_REACHED", "current": 2, "max": 2 }
}

Codes

HTTPcodeExtra fieldsWhenProduct should
400VALIDATION_FAILED—Malformed request bodyTreat as a bug in the integration; log it with the x-request-id.
404LICENSE_NOT_FOUND—Unknown key, wrong product, or check-in for an unknown or deactivated fingerprint. Deliberately indistinguishable.Activate: ask the operator to check the key. Check-in: switch to not_activated only after two consecutive 404s at least 1 hour apart.
409MACHINE_LIMIT_REACHEDcurrent, maxActivating a new fingerprint when the license already has max active machinesTell the operator to deactivate an unused installation or contact Digicom.
403LICENSE_NOT_USABLEstatus (suspended, revoked, expired or not_started)Activation on a license that can't be used now. Activation only: check-in always returns a signed file carrying the status instead.Show the status and tell the operator to contact Digicom (or wait for the start date).
404PRODUCT_NOT_FOUND—GET /client/keys/:productCode for an unknown or inactive productCheck the product code compiled into the build.
413PAYLOAD_TOO_LARGE—Request body over 16 KB (client API)Send less metadata/usage; treat as an integration bug.
429RATE_LIMITEDRetry-After headerToo many requests or failures from this IPWait at least Retry-After seconds before retrying.
503SIGNING_UNAVAILABLE—The product has no active signing key (Digicom operations error)Retry with backoff; keep the current file.

Any other 5xx response (envelope { "status": "fail", "data": { "message" } }) and any network error: retry with exponential backoff (1 minute doubling up to 1 hour) and keep the current file. Never change the license state because of a network or server error.

Why 404 covers several cases

The API must not reveal which license keys exist. Unknown keys, keys for another product, and unknown or deactivated fingerprints all return the same LICENSE_NOT_FOUND. LICENSE_NOT_USABLE can only be reached with a valid key, so revealing the status there is safe.

Why check-in never returns LICENSE_NOT_USABLE

HTTP errors are unsigned and could be spoofed. For check-in, a suspended, revoked or expired license returns 200 with a signed file carrying that status, so the product learns the decision from a trustworthy source.

For what operators should do about each code, see Troubleshooting.

On this page