NueForm

Error Handling

Understand the NueForm API error response format, error codes, and how to handle errors gracefully in your application.

The NueForm API uses conventional HTTP status codes and returns structured JSON error responses. This guide covers the response format, all possible error codes, and patterns for handling errors in your code.

Response Formats

Success Responses

Successful API calls return a JSON object with a data field. List endpoints also include a meta field with pagination information.

json
{
  "data": {
    "id": "clx1abc2d3e4f5g6h7i8j9k0",
    "title": "Customer Feedback",
    "status": "published",
    "created_at": "2026-01-15T09:30:00.000Z"
  }
}

With pagination metadata:

json
{
  "data": [
    {
      "id": "clx1abc2d3e4f5g6h7i8j9k0",
      "title": "Customer Feedback"
    },
    {
      "id": "clx2def3g4h5i6j7k8l9m0n1",
      "title": "Employee Survey"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Error Responses

Error responses return a JSON object with an error field containing the error code, a human-readable message, and the HTTP status code.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested form could not be found.",
    "status": 404
  }
}

Error Codes

The following table lists all error codes returned by the API:

CodeHTTP StatusDescription
BAD_REQUEST400The request is malformed, missing required fields, or contains invalid values.
UNAUTHORIZED401Authentication failed. The API key is missing, malformed, revoked, or expired.
FORBIDDEN403The authenticated user does not have permission to perform this action.
NOT_FOUND404The requested resource does not exist or is not accessible to the authenticated user.
CONFLICT409The request conflicts with the current state of the resource (e.g., a duplicate entry, or a form that can't be published yet).
RATE_LIMITED429Too many requests. See Rate Limits for details.
INTERNAL_ERROR500An unexpected error occurred on the server.

Example Error Responses

400 Bad Request

Returned when the request body is invalid or required fields are missing.

json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Field 'title' is required.",
    "status": 400
  }
}

401 Unauthorized

Returned when authentication fails for any reason.

json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "status": 401
  }
}

403 Forbidden

Returned when the user is authenticated but lacks permission. Common causes include accessing another user's resources or using a feature not available on the current plan.

json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available on your current plan.",
    "status": 403
  }
}

404 Not Found

Returned when the requested resource does not exist.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested form could not be found.",
    "status": 404
  }
}

409 Conflict

Returned when the request would create a duplicate or conflicts with existing data.

json
{
  "error": {
    "code": "CONFLICT",
    "message": "A form with this slug already exists.",
    "status": 409
  }
}

409 Conflict — publish blocked

Returned by POST /api/v1/forms/:id/publish (and by PUT /api/v1/forms/:id with published: true) when the form cannot go live yet. Nothing is published. reason says why, and question_ids lists the questions to fix. When upgrade_required is true, the form owner's plan needs an upgrade.

json
{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}
reasonWhat to fix
contract_requires_pro, data_node_requires_pro, booking_requires_pro, payment_connect_requires_pro, webhook_requires_proThe form owner's plan (the team owner's for team forms) doesn't include this feature. Upgrade, or remove it: delete the question, clear webhook_url, or switch the payment question to the standard option.
booking_*A booking question isn't ready to take bookings: connect or reconnect its calendar, or add its hours, timezone, duration options or confirmation-call number.
email_node_*An email step is missing its recipient, sender name, subject or body, or sends to {respondent.email} on a form that doesn't require login.
fuse_*A Fuse question has no Fuse form, its Fuse form is missing or unpublished, or its pinned session was archived.
composite_*A composite the form uses is unpublished, deleted or empty; composite_ids lists them.

If you create a form with published: true and its publish is blocked, the form is still created as a draft: the response is 201 Created with a publish_error object (reason, message, question_ids, upgrade_required), so retrying never creates a duplicate. When PUT /api/v1/forms/:id returns this error, your changes were saved (saved_as_draft: true) and only the publish failed.

429 Rate Limited

Returned when the rate limit has been exceeded. Includes a Retry-After header.

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later.",
    "status": 429
  }
}

500 Internal Error

Returned when an unexpected server error occurs. If this persists, contact support.

json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred.",
    "status": 500
  }
}

Voice API Errors

The Voice API adds these codes. Nothing that ends in an error is charged, and the extra fields sit next to code inside error.

CodeHTTP StatusDescription
INSUFFICIENT_CREDITS402Your balance doesn't cover the request. credits_required, credits_available and top_up_url say how much and where to get more.
TEXT_TOO_LONG413More spoken characters than one request takes (max_characters). Split the text into several requests.
CONTENT_BLOCKED422The text can't be spoken under our usage policy (categories).
VOICE_UNAVAILABLE422The voice doesn't exist or isn't yours to use (voice).
LANGUAGE_NOT_SUPPORTED_BY_VOICE422The voice can't speak that language (voice, language, supported_languages).
LINE_LANGUAGE_NOT_SUPPORTED_BY_VOICE422Some lines are in a language their own voice can't speak. mismatches lists each one (speaker, voice, voice_name, language, line_count) with up to four suggestions of voices that speak it. When native_voices is false, no voice speaks that language itself: the suggestions speak a neighbouring language and may not sound right.
INVALID_SCRIPT422The script can't be spoken as sent (reason, for example speaker_not_cast).
CONCURRENCY_LIMIT429Too many generations in progress at once for your account. Try again after Retry-After.
CAPACITY503No capacity right now. Try again after Retry-After.
WARMING_UP503The voice engine is starting. Try again after Retry-After.
MODERATION_UNAVAILABLE503The text couldn't be checked right now. Try again after Retry-After.
AI_UNAVAILABLE503auto_convert or auto_cast couldn't run right now. Try again after Retry-After.
DELETE_INCOMPLETE503A delete stopped partway. Send it again to finish.

FORBIDDEN (403) and CONFLICT (409) say why in reason: for example key_limit_reached, account_gate or scope_not_allowed, and quote_exceeds_max_credits, idempotency_conflict or request_in_progress.

json
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This request needs 30 credits; 12 are available. Nothing was charged.",
    "status": 402,
    "credits_required": 30,
    "credits_available": 12,
    "top_up_url": "https://nueform.io/wallet?tab=buy"
  }
}

Handling Errors in Code

JavaScript

Build a reusable API client that checks for errors and throws typed exceptions:

javascript
class NueFormApiError extends Error {
  constructor(code, message, status) {
    super(message);
    this.name = "NueFormApiError";
    this.code = code;
    this.status = status;
  }
}

async function nueformRequest(path, options = {}) {
  const response = await fetch(`https://app.nueform.io/api/v1${path}`, {
    ...options,
    headers: {
      "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const body = await response.json();

  if (!response.ok) {
    const { code, message, status } = body.error;
    throw new NueFormApiError(code, message, status);
  }

  return body;
}

// Usage
async function getForm(formId) {
  try {
    const { data } = await nueformRequest(`/forms/${formId}`);
    return data;
  } catch (error) {
    if (error instanceof NueFormApiError) {
      switch (error.code) {
        case "NOT_FOUND":
          console.error(`Form ${formId} does not exist.`);
          return null;
        case "UNAUTHORIZED":
          console.error("Check your API key configuration.");
          break;
        case "RATE_LIMITED":
          console.warn("Rate limited. Implement backoff and retry.");
          break;
        default:
          console.error(`API error [${error.code}]: ${error.message}`);
      }
    }
    throw error;
  }
}

Python

python
import os
import requests

class NueFormApiError(Exception):
    def __init__(self, code, message, status):
        super().__init__(message)
        self.code = code
        self.status = status

class NueFormClient:
    def __init__(self, api_key=None):
        self.api_key = api_key or os.environ["NUEFORM_API_KEY"]
        self.base_url = "https://app.nueform.io/api/v1"

    def request(self, method, path, **kwargs):
        url = f"{self.base_url}{path}"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }

        response = requests.request(method, url, headers=headers, **kwargs)
        body = response.json()

        if not response.ok:
            error = body["error"]
            raise NueFormApiError(
                error["code"], error["message"], error["status"]
            )

        return body

# Usage
client = NueFormClient()

try:
    result = client.request("GET", f"/forms/{form_id}")
    form = result["data"]
    print(f"Form: {form['title']}")

except NueFormApiError as e:
    if e.code == "NOT_FOUND":
        print(f"Form {form_id} does not exist.")
    elif e.code == "UNAUTHORIZED":
        print("Check your API key configuration.")
    elif e.code == "RATE_LIMITED":
        print("Rate limited. Implement backoff and retry.")
    else:
        print(f"API error [{e.code}]: {e}")

Best Practices

Always check the error field

Never assume a response is successful based on the presence of a body alone. Always check for the error field or verify the HTTP status code before processing the response.

Use specific error codes for control flow

Match on error.code (e.g., NOT_FOUND, RATE_LIMITED) rather than the HTTP status code. Error codes are stable, descriptive, and easier to reason about in application logic.

Log error details

Include the full error response in your logs for debugging. The code, message, and status together provide enough context to diagnose most issues without reproducing the request.

Handle 5xx errors with retries

Server errors (500 Internal Error) are typically transient. Implement retry logic with exponential backoff for these responses. Limit retries to 2--3 attempts before failing.

Do not expose error messages to end users

API error messages are designed for developers, not end users. Map API errors to user-friendly messages in your application.

If you receive persistent 500 Internal Error responses, please contact support with the request details and timestamps. Server errors are logged on our end and investigated.

Last updated: November 22, 2026