Errors

A successful call returns the plain resource or list. A failed call returns an envelope with a stable, machine readable code. Your code should branch on the code instead of the message text, because messages can change while codes don’t.

{
  "statusCode": 404,
  "success": false,
  "code": "RSP-002-007",
  "message": "The response couldn't be found.",
  "data": null
}

Field	Meaning
`statusCode`	The HTTP status, again
`success`	Always `false`
`code`	What went wrong, stable across versions
`message`	The code’s message in English (US)
`data`	Extra context for some errors, otherwise `null`
`errors`	Every invalid field, on a `400` about fields only

Field errors

When fields are invalid, the call returns 400, and errors names every invalid field in the order of the request’s parameters. The top level code is the first field’s code.

{
  "statusCode": 400,
  "success": false,
  "code": "PUB-001-001",
  "message": "The limit must be between 1 and 100.",
  "data": null,
  "errors": [
    { "field": "limit", "code": "PUB-001-001", "message": "The limit must be between 1 and 100." },
    { "field": "sort", "code": "PUB-001-005", "message": "The sort order must be asc or desc." }
  ]
}

field is the query parameter or the body property, in camelCase and dotted when nested. Every HTTP response, including an error, has an X-Request-Id header. Include it and the code when you contact support.

The OAuth token and revoke endpoints return errors in the OAuth format instead. See OAuth for apps.

Decide what to retry

Status	Retry?
`429`	Yes, after the seconds in the `Retry-After` header. See Rate limits.
`503`, `500`	Yes, with a growing wait. POST requests should carry an Idempotency-Key so a retry never runs twice.
`409` `PUB-002-003`	Yes, after a second, because the first request with that key is still running.
Any other `4xx`	No. The same request gets the same result until the request is fixed.

async function callUsertick(path, init = {}, attempt = 0) {
  const res = await fetch(`https://app.usertick.com/api/public/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.USERTICK_API_KEY}`, ...init.headers },
  });
  const retryable = res.status === 429 || res.status >= 500;
  if (retryable && attempt < 3) {
    const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt) * 1000;
    await new Promise((resolve) => setTimeout(resolve, wait));
    return callUsertick(path, init, attempt + 1);
  }
  if (res.status === 204) return null;
  const body = await res.json();
  if (!res.ok) throw new Error(`Usertick API error ${body.code} (${res.headers.get("X-Request-Id")})`);
  return body;
}

Every code

Each endpoint page in the API reference lists the codes that endpoint can return.

Credentials, scopes and plan

HTTP	Code	Message
401	`APK-004-001`	Send an API key or an access token in the Authorization header.
401	`APK-004-002`	The API key or access token is invalid, expired or revoked. Connect again with a valid one.
429	`APK-004-003`	This API key or app sent too many requests. Wait a minute and try again.
403	`APK-004-004`	This API key or app doesn’t have permission for this request. Grant it the required scope.
403	`APK-004-005`	Your plan doesn’t include the API and webhooks. To use them, upgrade to Pro.
403	`APK-004-008`	Your plan doesn’t include apps that use the API, such as Zapier. To use them, upgrade to Starter or higher.
429	`APK-004-006`	Your organization sent too many API requests. Wait a minute and try again.
401	`APK-004-007`	This credential is for another server. The MCP server takes only the access tokens an assistant gets when it signs in, and the REST API takes API keys and app tokens.
403	`AUTHZ-001-002`	Your role doesn’t have the required permission.
404	`AUTHZ-001-004`	The requested item couldn’t be found.
403	`AUTHZ-007-001`	Your role has access to selected surveys only, so this isn’t available.
429	`GEN-429-001`	Too many requests were sent. Wait a minute and try again.

Only an app receives AUTHZ-001-002 and AUTHZ-007-001, because its access token works with the permissions of the person who approved it. AUTHZ-007-001 answers a request that reaches every survey (erasing responses, a subscription’s delivery log) when that person’s role reaches selected surveys only. An API key or an AI assistant’s token receives APK-004-005 when the plan doesn’t include API keys, and an app’s token receives APK-004-008 when the plan doesn’t include apps. GEN-429-001 comes from the limit per IP address that applies before any credential is checked. See Rate limits.

Request format

HTTP	Code	Message
413	`GEN-000-413`	The request is too large. Send less data or a smaller file.
400	`PUB-001-001`	The limit must be between 1 and 100.
400	`PUB-001-002`	This cursor isn’t valid. Start again without one.
400	`PUB-001-003`	Send times in RFC 3339, such as 2026-09-30T10:00:00.000Z.
400	`PUB-001-004`	This value isn’t valid.
400	`PUB-001-005`	The sort order must be asc or desc.
400	`PUB-001-006`	Send a JSON body that this endpoint accepts.
400	`PUB-001-007`	The start of the window must come before its end.
400	`PUB-002-001`	Send an Idempotency-Key of 1 to 255 printable ASCII characters, without a space at either end.
409	`PUB-002-002`	This Idempotency-Key was used with a different request. Use a new key for a new request.
409	`PUB-002-003`	A request with this Idempotency-Key is still running. Try again in a moment.

Responses, notes and files

HTTP	Code	Message
400	`PUB-003-001`	The sentiment isn’t recognized. Use negative, neutral or positive.
400	`PUB-003-002`	Enter a valid email address.
400	`PUB-003-003`	Assign at most 500 people.
400	`PUB-003-004`	Filter by at most 50 surveys.
400	`PUB-003-005`	Every assignee must be a member of this organization.
404	`PUB-003-006`	The file couldn’t be found.
400	`PUB-003-007`	Send an email or a user ID, but only one of them.
400	`PUB-003-008`	The user ID is too long. Use 256 characters or fewer.
400	`PUB-003-009`	More than 100,000 responses were changed since this time. Use a later updatedSince.
400	`PUB-003-010`	More than 100,000 responses are linked to this contact. Narrow the list with from and to.
400	`APK-006-003`	The feedback type isn’t recognized. Use bug, idea, complaint, question or praise. The type filter of GET /responses also takes none.
400	`APK-006-004`	The urgency isn’t recognized. Use high, medium or low.
404	`APK-006-005`	The survey couldn’t be found.
400	`APK-006-007`	Include at least one change: a status, a type, an urgency or assignees.
400	`APK-006-012`	This event has no recent list. Use response.created, response.analyzed, response.status_changed or response.urgent.
400	`RSP-002-001`	The response status isn’t valid.
400	`RSP-002-002`	The note can’t be empty.
400	`RSP-002-003`	The note is too long.
404	`RSP-002-007`	The response couldn’t be found.
404	`RSP-002-009`	The note couldn’t be found.
403	`RSP-002-010`	You can only change your own notes.
400	`RSP-002-013`	The feedback type isn’t valid.
400	`RSP-002-014`	The urgency isn’t valid.
409	`RSP-002-023`	This response’s status was changed in another session before this change was saved. Reload the response to see its current status.

Surveys

HTTP	Code	Message
400	`PUB-005-001`	The channel isn’t recognized. Use website, link, qr or email.
400	`PUB-005-002`	The status isn’t recognized. Use draft, active, paused or archived.
409	`SRV-005-003`	The survey is archived, so it can’t be paused or resumed. Restore it from the archive first.
409	`SRV-005-004`	The survey is a draft, so it can’t be paused or resumed. Publish it first.
403	`SRV-005-005`	This survey was taken offline by Usertick and can’t be resumed. Contact support.

Erasure jobs

HTTP	Code	Message
404	`PUB-004-001`	The job couldn’t be found.
In the job	`PUB-004-002`	The job couldn’t be completed. Try again later.

PUB-004-002 is never returned as an HTTP status. It appears as the job’s error when the job failed after five tries.

Metrics

HTTP	Code	Message
400	`PUB-006-001`	The metric isn’t recognized. Use responses, nps or detractors.
400	`PUB-006-002`	The interval isn’t recognized. Use day, week or month.
400	`PUB-006-003`	The breakdown isn’t recognized. Use type, urgency, theme, category, sentiment, country or device.
400	`PUB-006-004`	This metric needs a surveyId.
400	`PUB-006-005`	The top value must be between 1 and 250.

Webhook subscriptions

HTTP	Code	Message
400	`PUB-007-001`	The delivery filter must be success or failed.
400	`APK-006-001`	The event isn’t recognized. Use response.created, response.analyzed, response.status_changed, response.classification_corrected, response.urgent, theme.spiking or workflow.step.
400	`APK-006-002`	This event doesn’t accept these filters. response.created accepts none, response.urgent doesn’t accept urgency, and theme.spiking accepts only themes.
400	`APK-006-010`	The theme isn’t recognized. Use theme IDs from GET /themes.
400	`APK-006-011`	Filter by at most 5,000 themes.
400	`APK-006-008`	Send the https URL that should receive the deliveries.
400	`APK-006-009`	The target URL must be 8 to 2048 characters.
400	`APK-006-013`	workflow.step needs both workflowId and stepId, and the other events take neither.
404	`APK-006-014`	The workflow step couldn’t be found. Add a Zapier step to the workflow, or pick one from GET /workflows/zapier-steps.
400	`WH-005-001`	This URL isn’t allowed. Use a public https address.
400	`WH-005-005`	Webhook URLs must start with https://.
409	`WH-005-006`	Another webhook already uses this URL. Subscribe with a different URL.
409	`WH-005-008`	This API key, app or organization has reached its limit of webhook subscriptions. Unsubscribe one, then try again.
409	`WH-005-010`	Another Zap already receives this workflow step. Turn that Zap off first.
404	`WH-007-001`	The webhook couldn’t be found.
404	`WH-014-002`	The delivery couldn’t be found.
409	`WH-014-003`	This delivery can’t be sent again because its full body wasn’t kept.
409	`WH-014-004`	This subscription has ended, so nothing more is sent to it.

Temporary problems

HTTP	Code	Message
500	`GEN-000-002`	An unexpected error occurred. Try again later.
503	`RSP-001-001`	Responses can’t be loaded right now. Try again in a moment.
503	`MED-003-503`	File storage isn’t available. Try again later.
503	`ANL-001-503`	Analytics storage is unavailable right now. Try again in a moment.

JavaScript SDK

REST API

API reference

Webhooks

MCP

Field errors

Decide what to retry

Every code

Credentials, scopes and plan

Request format

Responses, notes and files

Surveys

Erasure jobs

Metrics

Webhook subscriptions

Temporary problems

​Field errors

​Decide what to retry

​Every code

​Credentials, scopes and plan

​Request format

​Responses, notes and files

​Surveys

​Erasure jobs

​Metrics

​Webhook subscriptions

​Temporary problems

Field errors

Decide what to retry

Every code

Credentials, scopes and plan

Request format

Responses, notes and files

Surveys

Erasure jobs

Metrics

Webhook subscriptions

Temporary problems