401
JSON has an error string for a missing, invalid, or unavailable hashed API key.
Developer & API documentation
Error Handling
Error envelopes differ between the legacy company API and v1 public/mobile helpers. Integrations must inspect both HTTP status and the returned JSON rather than assuming one global schema.
Company API responses
403
Plan access can return an error string. Lifecycle blocks return success:false, ok:false, a top-level COMPANY_SUSPENDED, COMPANY_FROZEN, or COMPANY_DEACTIVATED code, a public-safe message, and a nested error object.
400 / 405 / 429
Employee validation and creation failures use 400; unsupported employee methods use 405; API authentication throttling can use 429. No numeric rate-limit contract or response headers are publicly guaranteed.
v1 public helper responses
These return {"ok":false,"error":{"code":"…","message":"…"}}. Implemented codes on the documented helpers are profile_not_found, employee_not_found, method_not_allowed, and service_unavailable. Do not apply mobile-login error codes to company API integrations.
Client strategy
Log a correlation generated by your own system, status code, safe error code/message, and timestamp—never credentials or personal payloads. Do not retry validation, authentication, plan, or lifecycle failures automatically. Use bounded backoff for transient 429 or 503 responses, but CardIQ publishes no Retry-After guarantee.
Continue reading
Control how employees represent your company externally
Explore the CardIQ Identity platform or review the workflow from verification through identity deactivation.
See how CardIQ Identity works View pricing