Error Handling

Error Response Format

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field validation failed",
    "details": [
      {
        "field": "email",
        "rule": "unique",
        "message": "A document with this email already exists"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Error Codes

Authentication Errors

• AUTH_REQUIRED — No authentication token provided
• AUTH_INVALID — Token is malformed or expired
• AUTH_INSUFFICIENT — Token lacks required scope

Validation Errors

• VALIDATION_ERROR — Field validation failed
• SCHEMA_MISMATCH — Document does not match collection schema
• REQUIRED_FIELD — Required field is missing

Handling Errors in Code

try {
  await db.collection("users").insert({ name: "Jane" });
} catch (error) {
  if (error.code === "VALIDATION_ERROR") {
    console.error("Validation failed:", error.details);
  } else if (error.code === "AUTH_REQUIRED") {
    // Redirect to login
  } else {
    console.error("Unexpected error:", error.message);
  }
}

Rate Limiting

API responses include rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1710532800