Errors

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

Error shape

{
  "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.

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.

Successful DELETE operations return 204 No Content. Do not attempt to parse a JSON body from a 204 response.

Get started

Core concepts

API reference

Error shape

HTTP statuses

Request IDs

Retry safely

​Error shape

​HTTP statuses

​Request IDs

​Retry safely

Error shape

HTTP statuses

Request IDs

Retry safely