Errors

All API errors follow a consistent format.

Error response format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "doc_url": "https://www.chatterforms.com/apidocs/errors#ERROR_CODE"
  },
  "meta": {
    "api_version": "2024-01-01"
  }
}

Some errors include extra fields (e.g. upgrade_url, required_plan for UPGRADE_REQUIRED).

Error codes

Authentication

Code	HTTP	Description
`INVALID_API_KEY`	401	Missing, invalid, or revoked API key

Request validation

Code	HTTP	Description
`PROMPT_REQUIRED`	400	Missing or empty prompt in create request
`PROMPT_TOO_LONG`	400	Prompt exceeds 4,000 characters
`INVALID_REQUEST`	400	Invalid parameters
`UNSUPPORTED_MEDIA_TYPE`	415	Request must be Content-Type: application/json
`METHOD_NOT_ALLOWED`	405	Wrong HTTP method

Plan restrictions

Code	HTTP	Description
`UPGRADE_REQUIRED`	403	Prompt requires a higher plan. Includes upgrade_url, required_plan

Not found

Code	HTTP	Description
`NOT_FOUND`	404	Form not found or not owned by your account

Server errors

Code	HTTP	Description
`FORM_GENERATION_FAILED`	413, 500	Generation failed
`DELETE_FAILED`	500	Failed to delete form
`INTERNAL_ERROR`	500	Unexpected server error

UPGRADE_REQUIRED (plan restriction)

When a prompt requires a feature above your plan:

{
  "success": false,
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "e-signature requires a Basic plan or higher...",
    "doc_url": "https://www.chatterforms.com/apidocs/errors#UPGRADE_REQUIRED",
    "upgrade_url": "https://www.chatterforms.com/pricing?plan=basic",
    "required_plan": "basic"
  },
  "meta": { "api_version": "2024-01-01" }
}

Handling errors

Node.js:

const res = await fetch(url, options);
const json = await res.json();

if (!json.success) {
  const { code, message } = json.error;
  if (code === 'UPGRADE_REQUIRED') {
    console.log('Upgrade at:', json.error.upgrade_url);
  }
  throw new Error(`${code}: ${message}`);
}

Python:

response = requests.post(url, json=body, headers=headers)

if not response.json().get('success'):
    error = response.json()['error']
    if error['code'] == 'UPGRADE_REQUIRED':
        print('Upgrade at:', error['upgrade_url'])
    raise Exception(f"{error['code']}: {error['message']}")