Error codes

Every error code the Response Submit API returns, with its HTTP status, the field it points at, and what it means.

A failed call returns application/problem+json (RFC 9457) with a stable code:

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "out_of_range",
  "detail": "Must be between 0 and 10.",
  "requestId": "4b1e0c7a92f3d811",
  "invalidParams": [
    {
      "name": "answers.how-likely-are-you-to-recommend-us",
      "code": "out_of_range",
      "message": "Must be between 0 and 10."
    }
  ]
}

Field	Meaning
`code`	Stable machine-readable code. With more than one problem it is `validation_failed`.
`detail`	Human-readable summary. The wording may change.
`requestId`	Quote it when contacting support.
`invalidParams`	Every problem with the request, each with `name` (the field, such as `answers.<key>`), its own `code`, and a `message`. There is one entry when `code` names a single check.

Validate Response lists the same codes in invalidParams, with a 200 status.

Handle codes, not messages

Match on code. New codes may be added over time. Handle an unknown code like any other error with the same HTTP status.

401 and 403 come from the API gateway, not the API. They have no code, only { "error": "..." }: api key is required, or publishable API keys cannot call /v2/admin routes. A 429 means an Admin API rate limit was reached.

Request

Code	Status	On	Meaning
`malformed_body`	`400`	body	Not valid JSON, or a field has the wrong type (for example a `status` other than `completed` or `partial`). For uploads: not multipart, no boundary, or a missing part.
`body_too_large`	`413`	body	The JSON body is larger than 100 KB.
`unsupported_field`	`400`, `422`	body, `device.<key>`, `answers.<key>`	A field the API does not know: a top-level body field or multipart part (`400`), or a device key, address part, or extra key inside an answer (`422`).
`form_id_mismatch`	`400`	`formId`	`formId` in the body differs from the one in the URL.
`invalid_idempotency_key`	`400`	`Idempotency-Key` header	`Idempotency-Key` must be 1 to 255 characters.
`idempotency_conflict`	`422`	—	The same `Idempotency-Key` or `externalId` was used in the last hour with a different body.
`request_in_progress`	`409`	—	The first request with this `Idempotency-Key` or `externalId` is still being queued. Retry after the `Retry-After` seconds.
`validation_failed`	`422`	—	More than one problem. Each one is in `invalidParams` with its own code.
`temporarily_unavailable`	`503`	—	The queue or the file storage is unavailable. Retry later with the same `Idempotency-Key`.

Form

Code	Status	On	Meaning
`invalid_form_id`	`422`	`formId`	`formId` in the URL is not a UUID.
`form_not_found`	`404`	`formId`	No form with this `formId` exists in the project.
`form_not_live`	`422`	`formId`	The form is not published, or its live version has no questions.
`api_channel_disabled`	`422`	`formId`	The API switch is off for this form (Distribution → API).
`outside_schedule`	`422`	`formId`	The form is outside its schedule.
`response_limit_reached`	`422`	`formId`	The form has reached its response limit.
`usage_quota_exceeded`	`422`	`formId`	The organization's response quota is used up (production keys only).

Body fields

Code	Status	On	Meaning
`language_not_available`	`422`	`language`	Not one of the form's languages.
`submitted_at_out_of_window`	`422`	`submittedAt`	Older than 15 days, or more than 2 minutes in the future.
`unknown_source_tracking_param`	`422`	`sourceTracking.<key>`	Not one of the form's source tracking parameters, or source tracking is off.
`user_not_found`	`422`	`user.userName`	No identified user with this `userName`. Create it with Identify User first.
`invalid_format`	`422`	`submittedAt`, `externalId`, `ipAddress`, `device`, `user.userName`, `answers.<key>`	Wrong format: `submittedAt` is not ISO 8601 with a time zone, `externalId` is not 1 to 255 characters, `ipAddress` is not IPv4 or IPv6, or an answer is not a valid email, website, date, phone number, or pattern match.
`invalid_type`	`422`	`device.<key>`, `answers.<key>`	Wrong JSON type, for example a number where a string or an array is expected.
`out_of_range`	`422`	`completionTimeInSeconds`, `answers.<key>`	Below 0, or outside the question's scale, number, or date limits.

Answers

All of these point at answers.<key>. See Answer formats for the value each question type takes.

Code	Status	Meaning
`unknown_question`	`422`	The key matches no question slug or UUID on the live version.
`duplicate_answer`	`422`	The same question is answered twice, by slug and by UUID.
`not_answerable`	`422`	The key is a screen that takes no answer (welcome, thank you, message, exit).
`unsupported_question_type`	`422`	A deprecated question type (annotation, UPI payment) that the API does not take.
`too_short`	`422`	Fewer characters than the question's minimum.
`too_long`	`422`	More characters than the question's maximum.
`invalid_option`	`422`	Not one of the question's options, rows, or columns.
`duplicate_option`	`422`	The same option is listed twice.
`other_not_allowed`	`422`	`otherText` sent without the Other option selected, or the question has no Other option.
`incomplete_path`	`422`	A nested selection path that stops before a leaf.
`too_few_selections`	`422`	Fewer selections than the question's minimum (choice, ranking, matrix).
`too_many_selections`	`422`	More selections than the question's maximum.
`too_many_items`	`422`	More question and answer pairs than the Q&A question allows.
`field_disabled`	`422`	An address part that is switched off on the question.
`unsupported_scale`	`422`	A rating matrix with text scale points, which the API cannot store yet.
`too_many_files`	`422`	More `fileId`s than the question's maximum.
`duplicate_file`	`422`	The same `fileId` is listed twice.
`file_not_found`	`422`	No upload with this `fileId`, it expired (24 hours), or it was uploaded for another question.
`file_already_used`	`422`	The `fileId` is already used by another response.
`mode_not_allowed`	`422`	The mode is off for the question, or the file's type does not match it (video, audio, photo).

Upload

Returned only by Upload File.

Code	Status	On	Meaning
`invalid_question`	`422`	`questionId`	`questionId` is not a UUID, is not on this form, or is not a file, signature, or video question.
`file_too_large`	`413`	`file`	Larger than the question allows, or than the upload limit.
`file_type_not_allowed`	`415`	`file`	Not one of the question's file types.

Custom API

Returned only by custom format URLs. name points at the rule's target field.

Code	Status	Meaning
`format_not_found`	`404`	No custom format with this slug on the form.
`path_matched_many`	`422`	A JSONPath rule matched several values where the field takes one.
`conversion_failed`	`422`	The payload value could not be converted to the field's type.
`option_not_mapped`	`422`	The payload value has no entry in the rule's option map.
`question_not_in_form`	`422`	A rule targets a question the live version does not have.

Which endpoints return what

Status	Submit	Validate	Upload	Custom format
Success	`202`	`200` (`valid` true or false)	`201`	`202`
`400`	✓	✓	✓	✓
`404`	✓	— (listed in `invalidParams`)	✓	✓
`409`	✓	—	—	✓
`413`	✓	✓	✓	✓
`415`	—	—	✓	—
`422`	✓	— (listed in `invalidParams`)	✓	✓
`503`	✓	—	✓	✓