API error reference
Every error includes type, code, message, doc_url, and request_id. Preserve X-Request-Id when troubleshooting. Retry only when the entry below recommends it.
invalid_api_key
The Bearer key is missing, malformed, unknown, or revoked. Create a key and send Authorization: Bearer ck_live_….
insufficient_scope
The key is valid but lacks the required scope. Create or rotate to a key with the named scope.
feature_not_on_plan
The workspace lacks the requested Starter or Pro feature. Review plans and quotas.
rate_limit_exceeded
The sustained or burst limit was exceeded. Wait for Retry-After, then retry with exponential backoff and jitter.
unsupported_media_type
The route requires Content-Type: application/json when a JSON body is present.
request_too_large
The request exceeded the 1 MiB public API body limit. Remove unused fields or split the operation.
invalid_json
The body is not valid UTF-8 JSON. Serialize once and sign or hash the exact transmitted bytes.
invalid_request
One or more request fields failed structural validation. Inspect the returned issues and param fields.
invalid_idempotency_key
Idempotency-Key must contain 1–255 characters.
idempotency_key_reused
The key was previously used with different raw request bytes. Use the original body or a new operation key.
idempotency_in_progress
Another request with the same key is still completing. Wait for Retry-After and send the identical body.
invalid_list_query
Certificate or template list filters are malformed. Check dates, statuses, limits, and CertKit ID prefixes.
invalid_cursor
The opaque pagination cursor is malformed or no longer usable. Restart listing without a cursor.
invalid_format
The requested download format is unsupported. Use png or pdf.
invalid_certificate
Certificate fields do not satisfy the published template schema. Correct missing, unknown, or oversized values.
invalid_revocation
The reason is invalid or the revocation cannot be applied to the current certificate state.
invalid_reinstatement
The certificate is not in a state that can be reinstated.
template_not_found
The template is absent, archived, outside the workspace, or has no published version.
certificate_not_found
The certificate ID does not exist in the authenticated workspace.
workspace_not_found
The API key no longer resolves to an active workspace.
external_id_exists
Another certificate already uses this workspace-level external_id. Use the returned existing certificate ID rather than issuing again.
monthly_quota_exceeded
The calendar-month certificate allowance is exhausted. Wait for the UTC reset or upgrade. Existing certificates remain active.
smtp_connection_unavailable
The selected SMTP connection is missing, paused, unverified, or belongs to another workspace. Verify it in SMTP settings.
api_temporarily_unavailable
The API dependency is temporarily unavailable. Retry with backoff and keep the request ID.
usage_temporarily_unavailable
Usage could not be read safely. Retry later; do not assume remaining quota.
verification_temporarily_unavailable
Public verification data could not be loaded. Retry later; do not treat this as a valid or revoked result.
internal_error
An unexpected server error occurred. Retry idempotent requests with the same key. If it persists, contact support with the request ID.