HTTP status codes & errors

Status code summary

Code	Status	Description
`200`	OK	Request succeeded
`202`	Accepted	Request accepted for processing (write operations)
`204`	No Content	Request succeeded, no content returned (deletions)
`400`	Bad Request	Invalid request parameters or data
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Insufficient permissions or invalid collection filter/order
`404`	Not Found	Requested resource does not exist
`405`	Method Not Allowed	HTTP method not supported for endpoint
`429`	Too Many Requests	Monthly API call limit exceeded (Free/Trial)
`500`	Internal Server Error	Server error (contact support)

Success responses

200 OK

Standard success response for read operations. The response body contains the requested data.

{
  "meta": {
    "count": 10,
    "next_page": 2,
    "previous_page": null
  },
  "data": [
    // Content items...
  ]
}

202 Accepted

Returned for write operations (POST, PUT, PATCH). The request has been accepted for asynchronous processing, with background tasks handling media uploads, validation, and webhook notifications.

{
  "status": "pending"
}

204 No Content

Returned for successful DELETE operations. No response body is included.

Error responses

All error responses follow a consistent format:

{
  "detail": "Error message describing what went wrong"
}

400 Bad Request

Indicates invalid request parameters or validation errors. Field-Specific Validation Errors:

{
  "title": ["You must specify a page title."],
  "slug": ["You must specify a page slug."]
}

General Error Message:

{
  "error": "Cannot create a new Collection Item. Collection Item Limit Reached."
}

Common 400 Error Causes:

Error	Description	Solution
Invalid locale	Locale not configured on account	Check configured locales in Settings
Invalid levels parameter	levels must be 1-5	Use integer between 1 and 5
Missing required field	Required field not provided	Include all required fields
Invalid field format	Field value doesn’t match expected type	Check field type requirements

Example Errors:

// Invalid locale (read operations)
{
  "locale": "The passed locale isn't configured on this account."
}

// Invalid locale (write operations)
{
  "fields": "Locales were specified without being configured on your account: 'xyz'."
}

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

401 Unauthorized

Authentication credentials are missing or invalid. Missing token:

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

Invalid token:

{
  "detail": "Invalid token."
}

Inactive or expired token:

{
  "detail": "Token inactive."
}

{
  "detail": "Token expired."
}

Common Causes:

Cause	Solution
Missing `auth_token` parameter	Add `?auth_token=YOUR_TOKEN` to URL
Missing Authorization header	Add `Authorization: Token YOUR_TOKEN` header
Invalid API token	Check token in ButterCMS Settings
Token inactive or expired	Contact support or generate a new token
Using Read token for Write operations	Request a Write API token

The API token you use for reading will not allow write operations. Contact support@buttercms.com to request a Write API token.

403 Forbidden

The authentication is valid, but the request is not permitted. This includes permission errors and invalid query parameters when filtering or ordering collections.

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

Invalid filter key (collections):

{
  "detail": "Invalid filter key nonexistent_field"
}

Common Causes:

Using an invalid field name to filter or order collection results
Attempting to access content from a different organization
Feature not enabled for your account

404 Not Found

The requested resource doesn’t exist.

{
  "detail": "Not found."
}

Common Causes:

Cause	Example	Solution
Invalid page slug	`/pages/blog/nonexistent-post/`	Check slug spelling
Invalid page type	`/pages/invalid-type/page-slug/`	Verify page type exists
Invalid collection key	`/content/invalid-collection/`	Check collection key
Invalid item ID	`/content/artists/99999/`	Verify item ID exists
Invalid pagination	`?page=999` (when only 10 pages exist)	Check total page count

Pagination Error:

{
  "detail": "Invalid Page."
}

405 Method Not Allowed

The HTTP method is not supported for the endpoint.

{
  "detail": "Method \"DELETE\" not allowed."
}

Solution: Check the REST Endpoints reference for supported methods.

429 Too Many Requests

Your account has been temporarily blocked after exceeding its monthly API call limit (Free/Trial accounts).

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

See Rate Limits & Throttling for details on limits and how to recover.

500 Internal Server Error

An error occurred on ButterCMS servers.

{
  "detail": "Internal server error"
}

If you receive this error:

Wait a moment and retry the request
Check ButterCMS Status for any incidents
Contact support@buttercms.com if the issue persists

Error handling best practices

JavaScript / Node.js

async function fetchFromButter(endpoint) {
  try {
    const response = await fetch(
      `https://api.buttercms.com/v2${endpoint}?auth_token=${API_TOKEN}`
    );

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 400:
          console.error('Validation error:', error);
          // Handle validation errors
          break;
        case 401:
          console.error('Authentication failed:', error.detail);
          // Redirect to login or refresh token
          break;
        case 404:
          console.error('Resource not found:', error.detail);
          // Show 404 page or fallback content
          break;
        case 429:
          console.error('API limit reached:', error.detail);
          // Respect Retry-After and wait until the monthly reset
          break;
        default:
          console.error('API error:', error);
      }

      throw new Error(error.detail || 'API request failed');
    }

    return await response.json();
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
}

Python

import requests
from time import sleep

def fetch_from_butter(endpoint, retries=3):
    url = f"https://api.buttercms.com/v2{endpoint}"

    for attempt in range(retries):
        try:
            response = requests.get(
                url,
                params={'auth_token': API_TOKEN}
            )

            if response.status_code == 200:
                return response.json()

            elif response.status_code == 400:
                error = response.json()
                raise ValueError(f"Validation error: {error}")

            elif response.status_code == 401:
                raise PermissionError("Authentication failed")

            elif response.status_code == 404:
                raise FileNotFoundError("Resource not found")

            elif response.status_code == 429:
                retry_after = response.headers.get("Retry-After")
                raise RuntimeError(f"API limit reached. Retry after {retry_after} seconds.")

            else:
                response.raise_for_status()

        except requests.RequestException as e:
            if attempt == retries - 1:
                raise
            sleep(1)

    raise Exception("Max retries exceeded")

Exponential backoff pattern

For transient errors (5xx), implement exponential backoff:

async function fetchWithRetry(endpoint, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetchFromButter(endpoint);
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      // Exponential backoff: 1s, 2s, 4s, 8s...
      const waitTime = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
  }
}

Webhook error responses

When your webhook endpoint receives notifications from ButterCMS:

Your Response	ButterCMS Behavior
`2xx`	Webhook delivered successfully
Non-`2xx` or timeout	Webhook delivery logged as failed

Webhook endpoints must respond within 5 seconds. Requests that exceed this timeout will be treated as failures.

Next steps

Rate Limits

Learn about API rate limits

Authentication

Fix authentication issues

Request Format

Review request requirements

Overview

Read API

Write API

Webhooks API

Image API

HTTP status codes & errors

Status code summary

Success responses

200 OK

202 Accepted

204 No Content

Error responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

405 Method Not Allowed

429 Too Many Requests

500 Internal Server Error

Error handling best practices

JavaScript / Node.js

Python

Exponential backoff pattern

Webhook error responses

Next steps

Rate Limits

Authentication

Request Format

Overview

Read API

Write API

Webhooks API

Image API

​Status code summary

​Success responses

​200 OK

​202 Accepted

​204 No Content

​Error responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​405 Method Not Allowed

​429 Too Many Requests

​500 Internal Server Error

​Error handling best practices

​JavaScript / Node.js

​Python

​Exponential backoff pattern

​Webhook error responses

​Next steps

Rate Limits

Authentication

Request Format

Status code summary

Success responses

200 OK

202 Accepted

204 No Content

Error responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

405 Method Not Allowed

429 Too Many Requests

500 Internal Server Error

Error handling best practices

JavaScript / Node.js

Python

Exponential backoff pattern

Webhook error responses

Next steps