Last updated
Fix a locked Integration Hub, a failed OAuth callback, an auto-map that can't reach your API, a lost API key or signing secret, and webhooks that aren't arriving.
How-to guides: Integrations, Developer / Partner API.
Integration Hub / connectors
"Integration Hub is locked." Integrations require a Pro (paid) tier. See Billing & plans.
"The OAuth callback failed / 'state expired.'" The connector OAuth state is short-lived (~15 minutes) and a stale callback is rejected. Just restart the connection from Sys Admin → Integration Hub.
"Auto-map can't reach my API URL." The ingest fetch is SSRF-guarded — private, loopback, link-local, and CGNAT hosts are blocked, and redirects aren't followed. It's also time-boxed and size-capped. If your spec is on an internal-only host or is huge, use pasted spec text instead of a URL, or a public OpenAPI URL.
"Auto-map produced a weird mapping." The mapping is a proposal — review and edit it before saving. Nothing syncs from a proposal alone; mapping never moves data on its own.
"Sync isn't flowing after connecting." Confirm you created an Integration (the connection alone doesn't define what syncs) and that the mapping is saved/attached. Vault-backed token storage for some providers is still gated, so a provider may connect for discovery/mapping without persisting tokens yet.
Partner API keys
"The Developer tab is locked." API access is Team-tier. See Billing & plans.
"I lost my API key / signing secret." Both the raw API key and the webhook signing secret are shown once at creation — CoverGuard only stores a hash/prefix. If you lost it, rotate the key (or recreate the webhook) to get a fresh one.
Error responses:
| Error | Meaning | Fix |
|---|---|---|
403 KEY_NOT_APPROVED | Approval is required and this key isn't approved | An admin approves it |
403 SUBSCRIPTION_INACTIVE | Owning account lapsed/downgraded below Team | Restore the plan |
403 COMPANY_SUBSCRIPTION_REQUIRED | The company behind the key isn't on an active plan with API access. The reason says which: no_company, company_unpaid, company_tier or seat_overage | See the table below |
403 FORBIDDEN_SCOPE | Key lacks the scope for that call | Use a key with the scope |
429 + Retry-After | Per-key rate limit or monthly quota hit | Back off / raise quota |
503 QUOTA_UNAVAILABLE | Usage accounting temporarily unavailable and the key fails closed | Retry shortly |
"My key worked yesterday and now returns a company subscription error"
The error code is COMPANY_SUBSCRIPTION_REQUIRED. API access belongs to your company, not to you personally, and it is re-checked on every call — so a billing change on the company is felt immediately, even by a key that was issued long before it. The reason in the response (at error.details.reason) names the fix:
reason | What happened | Fix |
|---|---|---|
no_company | The account isn't part of a CoverGuard company | Set one up at Account → Team |
company_unpaid | The company's plan lapsed or was cancelled | Renew or update billing |
company_tier | The plan is active but doesn't include API access | Upgrade to Team — /pricing |
seat_overage | Seats were reduced and you're now beyond the paid count | An owner/admin frees a seat or adds one |
"My webhooks stopped arriving"
If your calls to CoverGuard are also returning COMPANY_SUBSCRIPTION_REQUIRED, it's the same cause: event deliveries follow the same company check as calls, so they stop together. Fix the reason using the table above and deliveries resume on the next event — nothing is replayed for the time in between, so re-sync anything you rely on.
"My calls still succeed but carry an API access warning header"
The header is X-CoverGuard-API-Access-Warning, and it means you're in the warning period. The call worked, but the header names the reason it will start failing once company enforcement is switched on. Fix the reason it names before then — see the table above. Nothing else about the response changes while the header is present, so an integration that ignores it will keep working right up until it doesn't.
Webhooks
"My webhook isn't receiving events." Check, in order:
- The endpoint is HTTPS and returns 2xx quickly.
- The event filter includes the event type you expect.
- The endpoint is active.
- The per-endpoint delivery log (with retries) — it shows attempts and failures.
"How do I verify a delivery is really from CoverGuard?" Every delivery is HMAC-SHA256 signed with your endpoint's signing secret — verify the signature on your side using that secret.
"Team member changes aren't reaching my system." team.member.invited/updated/removed webhooks fire to the owner's registered endpoints; confirm the endpoint is registered under the account that owns the org.