Every error response includes a machine-readable error string, a request_id for support correlation, and an X-Request-Id response header. Failed requests are never billed.
{
"error": "over_quota",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Out of credits. Upgrade your plan or wait for the monthly reset.",
"upgrade_url": "https://knowfirm.com/pricing"
}invalid_requestMalformed request body, missing required fields, or invalid parameter values.
Check the request against the OpenAPI spec. Ensure JSON is valid and required fields are present.
invalid_or_missing_api_keyNo API key provided, or the key does not match any active key.
Pass a valid key via the X-API-Key header or Authorization: Bearer header. Create one in the dashboard.
over_quotaMonthly credit allowance exhausted for your plan.
Wait for the next calendar month reset, or upgrade your plan at /pricing.
payment_past_dueStripe subscription is past due after retry schedule.
Update your payment method in the billing portal at /dashboard/billing.
usage_ceilingHard monthly usage ceiling reached (enterprise/metered plans).
Contact support to raise the ceiling for your account.
ip_not_allowedRequest IP is outside the CIDR allowlist configured on the API key.
Update the key's IP allowlist in /dashboard or remove the restriction.
scope_deniedThe API key is scoped to specific operations and this one is not included.
Edit the key's scopes in /dashboard to include the needed operation, or use a key with broader scopes.
plan_not_entitledYour plan does not include this operation (e.g. batch enrich requires Starter or above).
Upgrade to a plan that includes the operation at /pricing.
account_suspendedAccount has been suspended.
Contact support for details.
not_foundNo matching entity found for the given identifiers.
Verify the identifier (EIN, name, CIK, LEI) is correct. Try alternative identifiers or a broader search.
rate_limitedMore than 120 requests per minute from this API key.
Back off and retry after the Retry-After header value. Use the X-RateLimit-Remaining header to self-throttle.
daily_limitRolling 24-hour request cap reached for this key.
Wait for the window to roll over, or contact support to raise the cap.
internal_errorUnexpected server error.
Retry the request. If it persists, contact support with the X-Request-Id value.
capability_failedThe data capability failed after input validation.
Retry the request. If it persists, contact support with the X-Request-Id value.
upstream_timeoutretryableWarehouse query exceeded the timeout (cold read or high load).
Retry after the Retry-After header (typically 2s). The response includes retryable: true.
upstream_unavailableretryableData warehouse is temporarily unreachable (connection pool restart, DNS).
Retry after the Retry-After header (typically 10s). The response includes retryable: true.
X-Request-Id — unique per request; include in support tickets.X-RateLimit-Limit — requests allowed per window (120).X-RateLimit-Remaining — requests remaining in the current window.X-RateLimit-Window — window duration in seconds (60).Retry-After — seconds to wait before retrying (on 429 and 503).request_id in the body and X-Request-Id in the headers. Include these when contacting support.