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

# Errors

> Handle Onlyform API failures with stable codes and request IDs.

Onlyform returns JSON error objects with a stable machine-readable `code`, a human-readable `message`, and a `request_id`.

## Error shape

```json theme={null}
{
  "type": "validation_error",
  "code": "INVALID_CURSOR",
  "message": "cursor must be a valid opaque pagination cursor.",
  "status": 422,
  "request_id": "req_8e3a302dc8c24cf29b27140f63185f51",
  "details": []
}
```

The `details` field appears only when the API has additional structured validation information.

## HTTP statuses

| Status | Meaning                                                            | Recommended action                                     |
| ------ | ------------------------------------------------------------------ | ------------------------------------------------------ |
| `400`  | The management request is malformed.                               | Correct the request before retrying.                   |
| `401`  | The API key is missing, invalid, expired, or revoked.              | Replace or rotate the key.                             |
| `403`  | The key lacks a required scope.                                    | Create a key with the required scope.                  |
| `404`  | The resource does not exist or is not accessible to the key owner. | Verify the ID and workspace access.                    |
| `409`  | The request conflicts with current state.                          | Inspect the error code and current resource.           |
| `412`  | An `If-Match` precondition failed.                                 | Fetch the form again and reapply the change.           |
| `422`  | A body, parameter, cursor, date, or URL failed validation.         | Correct the supplied value.                            |
| `429`  | The key exceeded its rate limit.                                   | Wait for `Retry-After`, then retry with backoff.       |
| `500`  | An unexpected server error occurred.                               | Retry safely and report the request ID if it persists. |

## Request IDs

Every API response contains an `X-Request-ID` header. Error bodies repeat it as `request_id`.

You may provide your own `X-Request-ID` when it contains 1–100 letters, numbers, periods, underscores, or hyphens. Otherwise, Onlyform generates one.

```bash theme={null}
curl https://api.onlyform.com/v1/me \
  --header "X-API-Key: $ONLYFORM_API_KEY" \
  --header "X-Request-ID: sync-job-20260731-001"
```

Log request IDs at service boundaries. Include the ID when contacting support about a failed API call.

## Retry safely

Retry `429` and transient `5xx` responses with bounded exponential backoff and jitter. Respect `Retry-After` when present.

Do not automatically retry:

* Validation failures.
* Authentication or authorization failures.
* Permanent deletes unless your application has confirmed the desired outcome.
* Form updates after a `412` until you fetch the latest ETag.

<Note>
  Successful `DELETE` operations return `204 No Content`. Do not attempt to parse a JSON body from a 204 response.
</Note>