Error codes

The error format

Every error from /api/v1 is an RFC 9457 problem with the content type application/problem+json. Program against code: it is stable. title and detail are written for people (often non-technical reviewers) and may change, so you can show detail as it is.

{
  "type": "https://commentkit.dev/docs/errors#edit_conflict",
  "title": "Someone else changed this",
  "status": 412,
  "code": "edit_conflict",
  "detail": "This feedback was updated by someone else a moment ago. Refresh to see the latest version."
}

type links to the entry on this page. validation_failed adds errors (messages per field) and rate_limited adds retry_after. New codes may be added; treat an unknown code by its HTTP status.

Codes

validation_failed422

Please check the highlighted fields. The request body or query did not pass validation. errors lists a plain-language message per field.

What to do: Correct the fields named in errors and send the request again.

unauthenticated401

Sign in required. There is no valid widget session: the access token is missing, expired, revoked or was issued to another website.

What to do: Refresh the session at /oauth/token, or sign in again.

invalid_grant400

Please sign in again. The one-time sign-in code or refresh token was expired, already used or does not match the PKCE verifier. Replaying an old refresh token ends the whole session.

What to do: Start the sign-in again.

invalid_agent_token401

Agent token required. The agent endpoint received no token, or a token that is unknown, expired or for another project.

What to do: Create an agent token in Project → Connect, or run commentkit login.

browser_not_allowed403

Agent tokens are server-side only. An agent token was sent from a web page (the request carried a browser Origin).

What to do: Use agent tokens from a terminal, CI or MCP client only.

scope_missing403

Not allowed for this token. The token or sign-in lacks the permission this action needs (reply or status), or a sign-in tried to create a token with more permissions than it has.

What to do: A project admin creates a new agent token with the permission ticked in Project → Connect, or you disconnect and connect again, ticking “Reply to feedback” or “Mark ready for review and link commits”.

forbidden403

Not allowed. The caller can see the project, but their role does not allow this action.

What to do: Ask a project admin for the right role.

no_access403

No access. The person (or the person who created the agent token) no longer has access to the project.

What to do: Ask the project team to invite the person again.

wrong_project403

Not allowed. The widget session belongs to a different project than the key or resource in the request.

What to do: Sign in again on this website.

origin_required403

Browser origin required. A widget endpoint was called without a browser Origin (and not as a same-origin GET).

What to do: Call widget endpoints from the website only; use the agent endpoints from servers.

origin_not_allowed403

Website not allowed. The website address is not on the project’s list of allowed websites.

What to do: A project admin adds the address (scheme, host and port, or a *. wildcard) under Project → Setup, step 1.

unknown_project404

Unknown project. No project has this publishable key.

What to do: Check the pk_live_… or pk_test_… key in your install snippet.

widget_disabled503

Feedback is paused. Feedback has been turned off for this site in the dashboard.

What to do: A project admin turns feedback back on in Project → Settings → Feedback widget (Pause feedback everywhere).

not_found404

Not found. The item does not exist, was deleted, or is not visible to this caller.

What to do: Check the id or reference, such as CK-12.

plan_required402

Feedback is read-only. The workspace plan has ended or does not include this feature (for example screenshots). Reading still works.

What to do: The workspace owner can renew or upgrade in Billing.

too_many_webhooks422

Too many webhooks. The project already has the most webhooks it can have (10), counting ones added by automations such as Zapier.

What to do: Remove a webhook in Project → Connect, or turn off a Zap you no longer use.

storage_full402

Storage is full. This website has used all of its file storage. Every website has its own storage, on every plan.

What to do: Delete files or old resolved tasks you no longer need. Feedback can still be sent without a screenshot.

edit_conflict412

Someone else changed this. The If-Match header no longer matches the thread’s or message’s ETag: someone changed it in the meantime.

What to do: Fetch it again, reapply the change and send the new ETag.

idempotency_key_reused422

This key was already used. The Idempotency-Key was already used in the last 24 hours for a different request (another body, path or method).

What to do: Use a new, unique key for every new action; reuse a key only to retry the exact same request.

idempotency_in_progress409

Still working on it. The first request with this Idempotency-Key has not finished yet.

What to do: Wait for Retry-After seconds and send the same request again; you then get its result.

verification_required403

Confirm your email first. A guest who has not entered their emailed code yet tried to do more than post their first comment.

What to do: Send the 6-digit code to POST /guest/verify, then use the session it returns.

pending_limit409

Confirm your email first. A guest who has not confirmed their email can post one comment; it is held until they do.

What to do: Confirm the code with POST /guest/verify; after that the guest can post as usual.

share_expired410

Link expired. The client link a guest used has expired, was turned off or has been used as often as allowed. Sending again cannot work.

What to do: Ask the person who sent the link for a new one. In the dashboard: Project → People, Client links.

guest_removed403

Access removed. The guest confirmed their email, but the team had removed them from the project. Their held comment is not published.

What to do: Ask the team to add the guest again (Project → People, Restore).

not_pending409

Already confirmed. The session is a normal, confirmed session, so there is no code to confirm or resend.

What to do: Nothing to do.

upload_missing409

Upload not finished. An upload was completed before the file arrived in storage.

What to do: Upload the file to the ticket URL, then call complete again.

size_mismatch422

Upload failed. The uploaded file was empty or larger than the size announced when the upload was created.

What to do: Create a new upload with the right size.

file_rejected422

File not accepted. The stored file is larger than announced, or its contents do not match the type it was announced as. With status 0 the widget refused the file before sending it: it is not an accepted type, is over the size limit, or the comment already has the most files it can take.

What to do: Upload a real file of an accepted type, within the size limit.

no_screenshot404

No screenshot. The feedback was sent without a screenshot.

What to do: Nothing to fetch; use the page, element and device details instead.

rate_limited429

Too many requests. The caller went over a rate limit. The response carries Retry-After and retry_after in seconds.

What to do: Wait for Retry-After seconds, then retry.

internal_error500

Something went wrong. An unexpected error on CommentKit’s side. Nothing about the request was wrong; the change may not have been saved.

What to do: Try again in a moment. If it keeps happening, contact support with the time of the request.

http_{status}

Request failed. Any other HTTP error, for example http_405 for a method that does not exist on that path.

What to do: Check the method and path against this reference.

Widget-only codes

The widget raises these itself, without an error answer from the server. They appear on CommentKitError.code, in the error event and in console warnings. Their status is 0 unless the entry shows one.

network_error0

Could not reach CommentKit. The request never got an answer: the device is offline, or an ad blocker, firewall or Content Security Policy blocked it. The draft is kept.

What to do: Check the connection. If it keeps happening, allow https://commentkit.dev in connect-src (see /docs/csp) and in any blocker.

thread_not_found404

Feedback not found. The widget tried to open a piece of feedback (from the list or a link in an email) that was deleted, or that this person can no longer see.

What to do: Nothing to fix in code. Ask the project team whether the feedback was deleted or the person’s access changed.

upload_cancelled0

Upload cancelled. A screenshot or file upload was stopped before it finished, usually because the person removed the file or closed the comment. Nothing was saved.

What to do: Nothing to do. Add the file again to send it.

upload_failed0

Upload failed. The screenshot or file could not be sent to storage (the storage host refused it or the connection dropped). status is the storage host’s answer, or 0 when there was none.

What to do: Try again. With a Content Security Policy, allow the storage host in connect-src and img-src (see /docs/csp).