API errors

Use this page to interpret errors returned by the Makeform REST API.

Every API route response includes an X-Request-Id header you can use to identify a failed request. Responses also report the API version in the makeform-version header.

Error format

Standard errors include statusCode, name, and message. statusCode is the HTTP status, name identifies the error, and message describes it. Some endpoints return a different shape for specific errors; see the note below.

Error names

Name	Status	Meaning
`bad_request`	400	The request is invalid.
`missing_api_key`	401	The request has no `Authorization` header.
`unauthorized`	401	The request is unauthorized.
`invalid_api_key`	403	The API key is unknown, or the request does not use a Bearer token.
`disabled_api_key`	403	The key is revoked or expired, or its owner’s account is disabled.
`forbidden`	403	The requested feature requires a higher plan.
`upgrade_required`	403	The requested feature requires a higher plan.
`not_found`	404	The resource was not found or you cannot access it.
`method_not_allowed`	405	The request method is not allowed.
`conflict`	409	The draft hash is stale.
`payload_too_large`	413	The request payload is too large.
`validation_error`	422	The request failed validation.
`missing_required_field`	422	A required field is missing.
`invalid_parameter`	422	A draft hash has an invalid format on `PATCH /forms/{id}/draft`.
`precondition_required`	428	The request is missing a required precondition, such as the draft hash when replacing a draft.
`rate_limit_exceeded`	429	The request was rate limited.
`internal_error`	500	An internal server error occurred.
`service_unavailable`	503	The service is unavailable. The response includes `Retry-After: 30`.

For form routes, a form you cannot access—including one you lack edit or delete permission for—returns 404 "Form not found", not 403. not_found also covers unknown or deleted forms, unknown submissions, and Headless forms on update or publish.

A missing or empty form name on create returns missing_required_field. A missing preview_config on PATCH /forms/{id}/draft also returns missing_required_field. Bad submissions-list query parameters, an empty PATCH /forms/{id} body, bad image uploads, and a non-email field selected for the email responder return validation_error.

To replace a draft, read draft_hash or ETag from GET /forms/{id} and send the hash as expected_draft_hash or draft_hash, or in the If-Match header. A missing hash returns 428; a stale hash returns 409. Publishing normalizes the draft and changes its draft_hash, so re-read the form before the next draft write.

Publish validation failures, invalid email-responder bodies, submission deletion during an active delivery, and image-upload rate limits can use different response shapes:

Publish failures return an error and type, with optional validationErrors. Status is 400, 403, 409, or 422. Types include CREDENTIAL_FIELD (422), TOS_VIOLATION (403), PRO_FEATURE_REQUIRED (403), INVALID_RESULT_BREAKDOWN (400), and INVALID_END_PAGE_UI (400).
An invalid email-responder body returns HTTP 400 with error: "Invalid request data" and details.
Deleting a submission while its delivery is still running returns HTTP 409 with an error-only body and a Retry-After: 10 header.
Deleting a form or submission that is on hold returns HTTP 409.
Image-upload rate-limit responses include retry_at and a Retry-After header.

Handle 429 responses

Requests can be rate limited. When you receive a 429, wait for the time in the Retry-After header before retrying. The REST API does not support Idempotency-Key.