Sheets JSON
Sign In Get Started
Back to Docs

Troubleshooting & FAQ

Common issues, solutions, and frequently asked questions.

Troubleshooting & FAQ

This guide covers common issues you might encounter when using SheetsJSON and how to resolve them.

Common Issues

“API key required” error

Problem: You’re receiving a 401 Unauthorized error with code api_key_required.

Solution:

  1. Check that your sheet has API key authentication enabled in the dashboard
  2. Ensure you’re including the API key in your 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
  1. Verify the API key is correct (no extra spaces or characters)

“Invalid API key” error

Problem: You’re receiving a 403 Forbidden error with code invalid_api_key.

Solution:

  1. Double-check your API key in the dashboard under your sheet settings
  2. Ensure you haven’t regenerated the key since copying it
  3. Check for copy/paste errors (leading/trailing whitespace)
  4. Verify you’re using the key for the correct sheet

“Sheet not found” error

Problem: You’re receiving a 404 Not Found error with code sheet_not_found.

Solution:

  1. Verify your API URL structure: /api/sheets/:account_slug/:sheet_slug
  2. Check that both the account slug and sheet slug are correct
  3. Look up the correct slugs in your dashboard
  4. Ensure the sheet hasn’t been deleted

Data not updating

Problem: Changes made in Google Sheets aren’t reflected in the API response.

Solution:

  1. Check cache settings: SheetsJSON caches responses. Wait for the cache TTL to expire or adjust the cache duration in your sheet settings.

  2. Force refresh: You can bypass cache by making a change to the sheet settings and saving.

  3. Verify Google connection: Ensure your Google account is still connected. Go to Settings in your dashboard to check.

“Token expired” error

Problem: You’re receiving a 503 Service Unavailable error with code token_expired.

Solution:

This means the Google OAuth token has expired and couldn’t be refreshed.

  1. Go to your SheetsJSON dashboard
  2. Navigate to Settings
  3. Click Reconnect Google Account
  4. Re-authorize access to your Google Sheets

Rate limit exceeded

Problem: You’re receiving 429 Too Many Requests errors.

Solution:

  1. Implement caching: Cache API responses on your end to reduce requests
  2. Add retry logic: Respect the Retry-After header and implement exponential backoff
  3. Upgrade your plan: Higher tiers have increased rate limits
  4. Use webhooks: Instead of polling, use webhooks to receive updates (coming soon) 
// 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 = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Write operations not working

Problem: POST, PUT, or DELETE requests return 403 Forbidden with write_api_not_enabled.

Solution:

Write API is a premium feature available on Pro plans and above.

  1. Check your current plan in Settings → Billing
  2. Upgrade to Pro to enable write operations
  3. After upgrading, try your request again

Google Sheets permission errors

Problem: You’re receiving errors about Google Sheets permissions.

Solution:

  1. Verify sheet sharing settings: Ensure the Google Sheet is accessible to your SheetsJSON-connected Google account

  2. Check ownership: You must have at least Editor access to use write operations

  3. Re-authorize: Try disconnecting and reconnecting your Google account in Settings

  4. Check Google Workspace policies: If using a corporate Google account, your organization may have restrictions on third-party app access

Frequently Asked Questions

General

What is SheetsJSON?

SheetsJSON is a service that converts your Google Sheets into RESTful JSON APIs. You can read, write, update, and delete data in your spreadsheets via simple HTTP requests.

How does pricing work?

We offer several plans:

  • Free: Limited API calls, read-only access
  • Pro: Higher limits, write API access
  • Business: Even higher limits, priority support
  • Enterprise: Custom limits, SLA, dedicated support

See our Pricing page for current details.

Is my data secure?

Yes. We use industry-standard security practices:

  • All connections use HTTPS/TLS encryption
  • API keys are hashed and never stored in plain text
  • We don’t store your spreadsheet data; we fetch it directly from Google
  • OAuth tokens are securely stored and regularly refreshed

API Usage

What’s the base URL for the API?

The base URL is https://api.sheetsjson.com. Your endpoints will look like:

https://api.sheetsjson.com/api/sheets/{account_slug}/{sheet_slug}

How do I find my account and sheet slugs?

  1. Log into your dashboard
  2. Your account slug is shown in Settings
  3. Sheet slugs are shown on each sheet’s detail page

You can also set custom API slugs for both your account and individual sheets.

Can I use SheetsJSON from the browser (client-side)?

Yes, but with caution:

  • Never expose your API key in client-side code
  • For public sheets that don’t require authentication, you can make direct requests
  • For authenticated requests, route them through your own backend server

What formats does the API support?

Currently, the API returns JSON only. All responses have Content-Type: application/json.

Are there any size limits?

  • Response size: No hard limit, but large sheets may be slow. Use pagination for best performance.
  • Request body: 10MB maximum for write operations
  • Sheets: We recommend keeping sheets under 50,000 rows for optimal performance

Google Sheets

Which Google Sheets features are supported?

  • Basic data in cells (text, numbers, dates)
  • Multiple sheets within a spreadsheet
  • Header rows for column names

Not currently supported:

  • Formulas (values are read, not formulas themselves)
  • Cell formatting
  • Charts and images
  • Comments
  • Protected ranges (write operations may fail)

How often does the API sync with my sheet?

Data is fetched in real-time from Google Sheets. However, responses are cached based on your cache TTL setting (default: 60 seconds) to improve performance and reduce Google API usage.

Can I use Google Sheets formulas?

Yes, but with limitations:

  • The API returns the computed values, not the formulas
  • Write operations will overwrite formulas with plain values
  • Consider using a separate “input” sheet for write operations if you rely on formulas

What happens if I rename or move my Google Sheet?

The SheetsJSON connection uses the Google Sheet’s unique ID, not its name or location. Renaming or moving the sheet won’t break the connection.

Plans & Billing

How do I upgrade my plan?

  1. Go to Settings → Billing in your dashboard
  2. Click Upgrade on your desired plan
  3. Complete the checkout process

Can I downgrade my plan?

Yes. Go to Settings → Billing and select a different plan. The change takes effect at the end of your current billing period.

Do unused API calls roll over?

No, API call limits reset at the start of each billing period.

What payment methods do you accept?

We accept all major credit cards (Visa, MasterCard, American Express, Discover) through our payment provider, Stripe.

Troubleshooting Tips

How can I debug API issues?

  1. Check response headers: Rate limit info is included in every response
  2. Log full responses: Error responses include helpful code and error fields
  3. Test with cURL: Isolate issues by testing directly with cURL before debugging your code
  4. Check the dashboard: View API logs and usage stats in your dashboard

Where can I get help?

  • Documentation: You’re here! Browse our docs for guides and references.
  • Contact Support: Contact us for technical assistance
  • Status Page: Check status.sheetsjson.com for service status

Still Need Help?

If you’re experiencing an issue not covered here, please contact our support team with:

  1. Your account email
  2. The sheet slug you’re having issues with
  3. The full error response (including headers if possible)
  4. A minimal code example that reproduces the issue

We typically respond within 24 hours on business days.

Was this page helpful? |