Errors

The Maiilo API uses standard HTTP status codes. Some errors have a plain-text body and others have a JSON body, so check the status code first, and only parse JSON for the responses shown as JSON below.

Error reference

Status	Body	Format	Cause	Fix
401	Missing API key	Plain text	No Authorization header was sent.	Send Authorization: Bearer YOUR_API_KEY.
401	Invalid API key	Plain text	The key does not exist or was deleted.	Check the key, or create a new one on the API keys page.
403	No active subscription found	Plain text	The account that owns the key has no active plan.	Sign in to the app to check the account’s plan.
404	{"error":"Not found"}	JSON	No template with this ID exists in the account that owns the key.	Check the template ID, and that the key belongs to the same account as the template.
404	{"error":"template_not_published"}	JSON	The template exists but has never been published.	Publish the template.
429	Plan limit exceeded	Plain text	The monthly request quota is used up.	Wait for the quota to reset, or upgrade. See Limits and quotas.
500	{"error":"Internal server error"}	JSON	An unexpected error on Maiilo’s side.	Retry later. If it continues, contact [email protected].

The two 404s

Both are 404, but they mean different things:

• {"error":"Not found"}: the ID is wrong, or the template belongs to a different account.
• {"error":"template_not_published"}: the ID is right, and the template needs publishing.

Which errors count toward your quota

Any request with a valid API key counts, including both 404s. A missing or invalid key (401) and requests over the limit (429) do not count. See Limits and quotas.

Handling errors in code

const res = await fetch(`https://app.maiilo.io/api/v1/templates/${id}`, {
  headers: { Authorization: `Bearer ${process.env.MAIILO_API_KEY}` },
});

if (!res.ok) {
  const type = res.headers.get('content-type') ?? '';
  const detail = type.includes('application/json')
    ? (await res.json()).error
    : await res.text();

  if (res.status === 404 && detail === 'template_not_published') {
    // The template exists but has never been published.
  }

  throw new Error(`Maiilo API ${res.status}: ${detail}`);
}

const template = await res.json();