Skip to main content

Troubleshooting

Most issues map to a specific HTTP status code. Inspect the response with curl -i or res.status first, then check the table below.

Using an AI assistant through MCP? See the dedicated MCP troubleshooting guide. MCP errors can use HTTP 200 with a JSON-RPC or tool-level error, so the guidance below is specific to the REST API.

401 Authentication Failed​

You've enabled an API key on the connection but the request didn't include it (or it's wrong). Sheet Best uses the X-Api-Key header — not Authorization.

curl -H 'X-Api-Key: YOUR_KEY' \
  'https://api.sheetbest.com/sheets/<id>'

Verify the key in Connection → Advanced Settings. See API Keys.

402 Payment Required​

You've used all of your plan's monthly requests, or the operation isn't available on your plan. Check X-RateLimit-Remaining on any response — when it reaches 0, requests are blocked until the next billing cycle. The error code returned is throttle.

Upgrade your plan to continue.

403 Forbidden / write_error​

Writes (POST, PATCH, PUT, DELETE) require Sheet Best to have edit access to the underlying Google Sheet. Two common causes:

  • The sheet is shared as Viewer instead of Editor (for "Anyone with the link" connections).
  • You're using a private connection but the authorized account no longer has edit access.

Re-share the sheet with edit permission, or reconnect via Connect with Drive.

404 Not Found​

  • The connection ID in the URL is wrong — copy it again from the dashboard.
  • The tab name is misspelled — tab names are case-sensitive. See Tabs.
  • The row index doesn't exist for that operation.

405 Method Not Allowed​

The endpoint doesn't accept that method. Common cases:

  • POST to /search — use GET with query parameters.
  • GET against an action endpoint that only accepts writes.

See the HTTP status codes reference.

Numbers return as strings​

This is the default. Append _raw=1 to any GET request to receive native types:

curl 'https://api.sheetbest.com/sheets/<id>?_raw=1'

See Data Formats.

Empty array on GET​

  • The sheet has headers but no data rows.
  • Filters in the URL didn't match anything — try the bare endpoint to confirm rows exist.
  • The wrong tab is being queried — verify with /tabs/<TabName>.

CORS errors in the browser​

If you've enabled an API key, calling the API directly from a browser exposes the key. The recommended pattern is to proxy requests through your own backend and keep the key server-side.

Still stuck?​

  • Check the FAQ.
  • Inspect the response headers — X-RateLimit-Remaining, X-Sheet-Rows, and X-Sheet-Columns often reveal the cause.
  • Contact support.