> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope, field errors, every code the REST API returns, and which errors to retry.

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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

> [!NOTE]
>
> The OAuth token and revoke endpoints return errors in the OAuth format instead. See [OAuth for apps](https://docs.usertick.com/developers/api/oauth.md#token-endpoint-errors).

## Decide what to retry

| Status | Retry? |
| - | - |
| `429` | Yes, after the seconds in the `Retry-After` header. See [Rate limits](https://docs.usertick.com/developers/api/rate-limits.md). |
| `503`, `500` | Yes, with a growing wait. POST requests should carry an [Idempotency-Key](https://docs.usertick.com/developers/api/idempotency.md) 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. |

```javascript theme={null}
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](https://docs.usertick.com/developers/api/rate-limits.md#the-limit-per-address).

### 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.