Error Codes

This page provides a complete reference of all error codes returned by the SheetsJSON API, along with explanations and suggested solutions.

Error Response Format

All errors follow a consistent JSON structure:

{
  "error": "Human-readable error message",
  "code": "machine_readable_code"
}

Some errors include additional context:

{
  "error": "An unexpected error occurred",
  "code": "internal_error",
  "details": "Additional debugging information"
}

HTTP Status Codes

Status	Meaning	Common Causes
`200`	OK	Request succeeded
`201`	Created	Resource created successfully (POST)
`400`	Bad Request	Invalid parameters or request body
`401`	Unauthorized	Missing authentication
`403`	Forbidden	Invalid credentials or insufficient permissions
`404`	Not Found	Resource doesn’t exist
`429`	Too Many Requests	Rate limit exceeded
`502`	Bad Gateway	Error from Google Sheets API
`503`	Service Unavailable	Sheet is paused or temporarily unavailable
`500`	Internal Server Error	Unexpected server error

Error Code Reference

Authentication Errors

`api_key_required`

HTTP Status: 401 Unauthorized

Message: “API key required.”

Cause: The sheet requires authentication but no API key was provided.

Solution: Include your API key in the request:

# Using Authorization header (recommended)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.sheetsjson.com/api/sheets/account/sheet

# Using X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.sheetsjson.com/api/sheets/account/sheet

# Using query parameter (less secure)
curl "https://api.sheetsjson.com/api/sheets/account/sheet?api_key=YOUR_API_KEY"

`invalid_api_key`

HTTP Status: 403 Forbidden

Message: “Invalid API key”

Cause: The provided API key doesn’t match the sheet’s API key.

Solution:

Verify you’re using the correct API key from your dashboard
Check for typos or extra whitespace
Ensure you haven’t revoked or regenerated the key

Resource Errors

`account_not_found`

HTTP Status: 404 Not Found

Message: “Account not found”

Cause: The account slug in the URL doesn’t exist.

Solution:

Verify the account slug in your dashboard under Settings
Check for typos in the URL
Ensure the account hasn’t been deleted

`sheet_not_found`

HTTP Status: 404 Not Found

Message: “Sheet not found”

Cause: The sheet slug doesn’t exist or doesn’t belong to the specified account.

Solution:

Verify the sheet slug in your dashboard
Ensure the sheet hasn’t been deleted
Check you’re using the correct account slug

`sheet_paused`

HTTP Status: 503 Service Unavailable

Message: “Sheet is paused”

Cause: The sheet owner has temporarily paused API access.

Solution:

Contact the sheet owner to resume access
If you’re the owner, unpause the sheet from your dashboard

Request Errors

`invalid_body`

HTTP Status: 400 Bad Request

Message: “Invalid request body. Expected a JSON object or array of objects.”

Cause: The request body is not valid JSON or doesn’t match the expected format.

Solution:

Ensure your body is valid JSON
For POST requests, send either a single object {} or an array [{}, {}]
For PUT requests, send a single object {}
Check your Content-Type header is application/json

Example of valid request:

curl -X POST "https://api.sheetsjson.com/api/sheets/account/sheet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product", "price": "29.99"}'

`invalid_row_number`

HTTP Status: 400 Bad Request

Message: “Invalid row number. Must be a positive integer greater than the header row.”

Cause: The row number in PUT or DELETE requests is invalid.

Solution:

Row numbers must be positive integers
Row 1 is reserved for headers
Data rows start at row 2
Ensure the row number is within your sheet’s range

`missing_headers`

HTTP Status: 400 Bad Request

Message: “Could not determine sheet headers. Ensure the sheet has a header row.”

Cause: The API couldn’t read the column headers from your sheet.

Solution:

Ensure your sheet has a header row (row 1)
Headers should be non-empty text values
Check that the Google Sheet is accessible

Permission Errors

`write_api_not_enabled`

HTTP Status: 403 Forbidden

Message: “Write API is not enabled for your plan. Please upgrade to Pro or higher.”

Cause: Your plan doesn’t include write API access.

Solution:

Upgrade to Pro or higher to enable write operations
Write operations include POST, PUT, and DELETE

Rate Limiting Errors

`rate_limited`

HTTP Status: 429 Too Many Requests

Message: “Rate limit exceeded. Please retry after X seconds.”

Cause: You’ve exceeded the request rate limit for your plan.

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705764000
Retry-After: 45

Solution:

Wait for the time specified in Retry-After header
Implement exponential backoff in your code
Consider caching responses
Upgrade your plan for higher limits

Example retry logic:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After')) || Math.pow(2, i);
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

`usage_limit_exceeded`

HTTP Status: 429 Too Many Requests

Message: “Monthly API request limit exceeded. Please upgrade your plan.”

Cause: You’ve exceeded your monthly API request quota.

Solution:

Wait until the next billing cycle
Upgrade your plan for a higher quota
Review your API usage in the dashboard

Google Sheets Errors

`google_api_error`

HTTP Status: 502 Bad Gateway

Message: “Failed to [read/write/update/delete] [from/to] sheet: [details]”

Cause: An error occurred when communicating with Google Sheets.

Common causes:

Google Sheets API is temporarily unavailable
The underlying Google Sheet was deleted or moved
Permission issues with the Google Sheet
The sheet is too large or complex

Solution:

Retry the request after a short delay
Verify the Google Sheet still exists and is accessible
Check the Google Sheets API status at status.cloud.google.com

`token_expired`

HTTP Status: 503 Service Unavailable

Message: “Unable to access sheet. The owner needs to re-authenticate.”

Cause: The Google OAuth token has expired and couldn’t be refreshed.

Solution:

If you’re the sheet owner, re-authenticate in your dashboard
Go to Settings and reconnect your Google account
If you’re not the owner, contact them to re-authenticate

Internal Errors

`internal_error`

HTTP Status: 500 Internal Server Error

Message: “An unexpected error occurred”

Cause: An unexpected error occurred on the server.

Solution:

Retry the request after a short delay
If the error persists, contact support with the error details
Check our status page for any ongoing incidents

Handling Errors in Your Code

JavaScript / TypeScript

async function fetchSheetData(accountSlug, sheetSlug, apiKey) {
  const response = await fetch(
    `https://api.sheetsjson.com/api/sheets/${accountSlug}/${sheetSlug}`,
    {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    
    switch (error.code) {
      case 'api_key_required':
      case 'invalid_api_key':
        throw new Error('Authentication failed. Check your API key.');
      
      case 'sheet_not_found':
        throw new Error('Sheet not found. Verify the URL.');
      
      case 'rate_limited':
        const retryAfter = response.headers.get('Retry-After');
        throw new Error(`Rate limited. Retry after ${retryAfter}s`);
      
      default:
        throw new Error(error.error || 'Unknown error occurred');
    }
  }

  return response.json();
}

Python

import requests

def fetch_sheet_data(account_slug, sheet_slug, api_key):
    response = requests.get(
        f'https://api.sheetsjson.com/api/sheets/{account_slug}/{sheet_slug}',
        headers={'Authorization': f'Bearer {api_key}'}
    )
    
    if not response.ok:
        error = response.json()
        code = error.get('code', 'unknown')
        message = error.get('error', 'Unknown error')
        
        if code in ('api_key_required', 'invalid_api_key'):
            raise AuthenticationError(message)
        elif code == 'sheet_not_found':
            raise NotFoundError(message)
        elif code == 'rate_limited':
            retry_after = response.headers.get('Retry-After', 60)
            raise RateLimitError(message, retry_after)
        else:
            raise APIError(message)
    
    return response.json()

Elixir

defmodule MyApp.SheetsClient do
  def fetch_sheet_data(account_slug, sheet_slug, api_key) do
    url = "https://api.sheetsjson.com/api/sheets/#{account_slug}/#{sheet_slug}"
    headers = [{"Authorization", "Bearer #{api_key}"}]
    
    case Req.get(url, headers: headers) do
      {:ok, %{status: 200, body: body}} ->
        {:ok, body}
      
      {:ok, %{status: 401, body: %{"code" => "api_key_required"}}} ->
        {:error, :api_key_required}
      
      {:ok, %{status: 403, body: %{"code" => "invalid_api_key"}}} ->
        {:error, :invalid_api_key}
      
      {:ok, %{status: 404, body: %{"code" => "sheet_not_found"}}} ->
        {:error, :sheet_not_found}
      
      {:ok, %{status: 429, headers: headers}} ->
        retry_after = get_retry_after(headers)
        {:error, {:rate_limited, retry_after}}
      
      {:ok, %{status: status, body: body}} ->
        {:error, {:api_error, status, body}}
      
      {:error, reason} ->
        {:error, {:network_error, reason}}
    end
  end
  
  defp get_retry_after(headers) do
    headers
    |> Enum.find(fn {k, _} -> String.downcase(k) == "retry-after" end)
    |> case do
      {_, value} -> String.to_integer(value)
      nil -> 60
    end
  end
end

Need Help?

If you’re encountering errors not listed here, or need additional assistance:

Check our FAQ for common issues
Review the API Reference for correct usage
Contact Support with your error details