Errors

SheetBridge uses standard HTTP status codes and returns error details in JSON format.

Status Codes

Error Response Format

Error responses vary depending on the error type. All errors include an error field, and may include additional fields:

{
  "error": "Error message here",
  "message": "Additional message (optional)",
  "details": "Additional details if available (optional)",
  "rate_limited": false
}

Fields

• error - Always present (required)
• message - Present in some errors (optional)
• details - Present in exception errors (optional)
• rate_limited - Present in rate limit errors (optional)

Common Errors

401 Unauthorized

Invalid or missing Bearer token:

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

Solution: Check that you're including a valid Bearer token in the Authorization header.

403 Forbidden

Token doesn't have access to the specified bridge:

{
  "error": "Forbidden",
  "message": "Token does not have access to this bridge"
}

Solution: Ensure your token belongs to the bridge owner.

404 Not Found

Bridge or record not found:

{
  "error": "Not Found",
  "message": "Bridge or record not found"
}

Solution: Verify the bridge ID, sheet ID, and record ID are correct.

422 Unprocessable Entity

Validation error, such as ambiguous filter column:

{
  "error": "Unprocessable Entity",
  "message": "Ambiguous filter column: 'name' matches multiple columns"
}

Solution: Use more specific column names or provide the exact column name.

429 Too Many Requests

Rate limit exceeded:

{
  "error": "Rate limit exceeded",
  "rate_limited": true,
  "message": "Too many requests. Please try again later."
}

Solution: Implement retry logic with exponential backoff, or use a Service Account for higher limits.

Related Topics

• Rate Limiting - Understand rate limits and quotas
• Authentication - Set up proper authentication
• API Reference - See error responses for each endpoint