Errors

Format

Errors are JSON objects with a human-readable error, and usually a machine-readable code:

{
  "code": "TEMPLATE_NOT_FOUND",
  "error": "Template not found"
}

Branch on the HTTP status and code; show error to humans.

Status codes

Status	Meaning
200	Success
400	Invalid request — missing required variable, value too long
401	Not authenticated — missing, invalid or revoked API key
404	Not found, or not yours
408	PDF generation exceeded 30 seconds
500	Unexpected server error

Error codes

Code	Status	When
UNAUTHENTICATED	401	No valid session or API key
TEMPLATE_NOT_FOUND	404	Unknown template ID, or owned by someone else
VARIABLE_TOO_LONG	400	A value exceeds the variable’s maxLength

A missing required variable returns 400 with "error": "Required variable \"<name>\" is missing".

Handling errors

const res = await fetch(url, options);

if (!res.ok) {
  const { code, error } = await res.json().catch(() => ({}));
  switch (code) {
    case 'VARIABLE_TOO_LONG':
      throw new Error(`Value too long: ${error}`);
    case 'TEMPLATE_NOT_FOUND':
      throw new Error('Unknown template — check the ID and the API key owner');
    case 'UNAUTHENTICATED':
      throw new Error('Check IMPRIME_API_KEY');
    default:
      throw new Error(`[${res.status}] ${error ?? 'export failed'}`);
  }
}