API error codes

A detailed reference for all possible ButterCMS API error codes and how to resolve them.

HTTP status codes overview

Status Code	Category	Description
200 OK	Success	Request succeeded, data returned
202 Accepted	Success	Write request accepted for processing
400 Bad Request	Client Error	Invalid request parameters
401 Unauthorized	Client Error	Authentication failed
403 Forbidden	Client Error	Access denied or resource conflict
404 Not Found	Client Error	Resource doesn’t exist
429 Too Many Requests	Client Error	Monthly API call limit exceeded (Free/Trial)
500 Internal Server Error	Server Error	Server-side issue

---

Authentication errors (401)

Missing API token

{
  "detail": "Authentication credentials were not provided"
}

Cause: No API token was included in the request.

Solution: Include your API token either as:

• Query parameter: ?auth_token=YOUR_TOKEN
• Authorization header: Authorization: Token YOUR_TOKEN

Invalid API token

{
  "detail": "Invalid token"
}

Cause: The provided API token is incorrect or has been revoked.

Solution:

1. Go to Settings > API Tokens in your dashboard
2. Copy the correct Read API Token
3. Ensure there are no extra spaces or characters

Write token required

{
  "detail": "Authentication credentials were not provided"
}

Cause: Attempting to create/update content with a Read API token.

Solution: Write operations require a Write API Token. Contact [e-mail] to request write access.

---

Bad request errors (400)

Invalid query parameters

{
  "detail": "levels query parameter should be an integer between 1 and 5 (inclusive)"
}

Cause: Query parameter value is out of valid range or wrong type.

Solution: Check the API documentation for valid parameter values:

• levels: Integer 1-5
• page: Positive integer
• page_size: Integer 1-100

Invalid locale parameter

{
  "detail": "Invalid locale parameter"
}

Cause: The specified locale doesn’t exist or is not enabled.

Solution:

1. Go to Settings > Localization in your dashboard
2. Verify the locale slug matches your API request
3. Locale slugs are typically lowercase (e.g., en, es, fr-ca)

Invalid search parameters

{
  "detail": "Invalid search query"
}

Cause: Search query is malformed or contains invalid characters.

Solution: Ensure search queries:

• Are URL-encoded if containing special characters
• Don’t exceed maximum length (typically 256 characters)
• Use valid search syntax

Invalid field filter

{
  "detail": "Invalid fields parameter"
}

Cause: Requested fields don’t exist or have invalid syntax.

Solution: Check that:

• Field names match your content schema exactly
• Use dot notation for nested fields: fields.hero.title
• Fields parameter is comma-separated without spaces

---

Forbidden errors (403)

Multiple pages found

{
  "detail": "Multiple pages found for the given slug"
}

Cause: When using page_type=*, multiple pages share the same slug.

Solution:

1. Specify a page type instead of *: /pages/landing_page/homepage
2. Or ensure slugs are unique across all page types

Access Denied

{
  "detail": "You do not have permission to perform this action"
}

Cause: Your account or API token doesn’t have access to this resource.

Solution:

• Verify you’re using the correct account’s API token
• Check if your plan includes access to this feature
• Contact support if you believe this is an error

---

Not found errors (404)

Page not found

{
  "detail": "Page matching query does not exist"
}

Cause: No page exists with the specified page type and slug.

Solution:

1. Verify the page is published (not draft)
2. Check the slug matches exactly (case-sensitive)
3. Confirm the page type key is correct
4. Verify the page exists in the dashboard

Collection not found

{
  "detail": "Collection matching query does not exist"
}

Cause: The collection key doesn’t exist.

Solution:

1. Check the collection key in Content Types > Collections
2. Collection keys use underscores, not hyphens
3. Keys are case-sensitive

Blog Post not found

{
  "detail": "Post matching query does not exist"
}

Cause: No blog post exists with the specified slug.

Solution:

1. Verify the post is published
2. Check the slug is correct
3. Ensure you’re not including /blog/ prefix in the slug

---

Rate limit errors (429)

Too Many Requests

{
  "detail": "API Calls limit reached."
}

Cause: A Free or Trial account exceeded its monthly API call limit and has been temporarily blocked.

Solution:

1. Check usage: Review API calls in your billing dashboard
2. Reduce calls: Cache responses and avoid polling
3. Wait for reset: The block lifts at the next billing cycle
4. Upgrade if needed: Paid plans are not blocked for monthly API overages

Rate Limit Response Headers:

Header	Description
Retry-After	Seconds to wait before retrying (provided by API when rate limited)

When you exceed your plan’s monthly API call limit, the Retry-After value indicates the seconds remaining until the end of the current billing month when your limit resets.

Retry Logic Example:

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`API limit reached. Retrying in ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      return response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

---

Validation Errors

Content validation failed

{
  "detail": {
    "fields": {
      "title": ["This field is required."],
      "slug": ["A page with this slug already exists."]
    }
  }
}

Cause: Content being created/updated fails validation rules.

Solution: Check each field mentioned in the error:

• Ensure required fields are provided
• Verify slugs are unique
• Check field values meet validation rules (min/max length, format)

Schema Mismatch

{
  "detail": "Field 'hero_image' is not defined in this page type"
}

Cause: Trying to set a field that doesn’t exist in the content schema.

Solution:

1. Check the page type schema in Content Types
2. Ensure field names match exactly
3. Update your code to match the current schema

---

Server errors (500)

Internal Server Error

{
  "detail": "An unexpected error occurred. Please try again later."
}

Cause: An unexpected error on ButterCMS servers.

Solution:

1. Wait a few minutes and retry
2. Check the API Status Page
3. If persistent, contact support with:
   • The exact endpoint you’re calling
   • Request parameters
   • Timestamp of the error

---

Error handling best practices

JavaScript/TypeScript

async function safeFetch(fetchFn) {
  try {
    const response = await fetchFn();
    return { data: response.data, error: null };
  } catch (error) {
    const status = error.response?.status;
    const detail = error.response?.data?.detail;

    console.error(`ButterCMS Error [${status}]:`, detail);

    // Handle specific errors
    switch (status) {
      case 401:
        return { data: null, error: 'Authentication failed. Check your API token.' };
      case 404:
        return { data: null, error: 'Content not found.' };
      case 429:
        return { data: null, error: 'API limit reached. Please wait for the monthly reset.' };
      default:
        return { data: null, error: detail || 'An unexpected error occurred.' };
    }
  }
}

Python

from butter_cms import ButterCMS
from butter_cms.exceptions import ButterCMSError

client = ButterCMS('your-api-token')

try:
    page = client.pages.get('landing_page', 'homepage')
except ButterCMSError as e:
    if e.status_code == 401:
        print("Authentication failed. Check your API token.")
    elif e.status_code == 404:
        print("Page not found.")
    elif e.status_code == 429:
        print("API limit reached. Please wait for the monthly reset.")
    else:
        print(f"Error {e.status_code}: {e.message}")

---

Quick reference table

Error Code	Common Cause	Quick Fix
401	Missing/invalid token	Check Settings > API Tokens
400	Invalid parameters	Verify parameter values
403	Wrong page type	Specify exact page type
404	Content not published	Publish the content
429	Too many requests	Check usage, reduce calls, wait for monthly reset
500	Server issue	Wait and retry, check status

---

Related resources

Common Errors

Step-by-step solutions for common issues

Debugging Guide

How to debug your integration

API Reference

Full API documentation

Contact Support

Get help from our team