Skip to main content
The ChatGrid API uses conventional HTTP status codes and returns a consistent JSON error envelope for every error response.

Error response format

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Invalid request body",
  "details": [
    {
      "code": "too_small",
      "path": "name",
      "message": "String must contain at least 1 character(s)"
    }
  ]
}
FieldTypeDescription
objectstringAlways "error"
statusintegerHTTP status code
codestringMachine-readable error code
messagestringHuman-readable description
detailsarrayOptional. Field-level validation errors

Common error codes

400 Bad Request

CodeMeaning
validation_errorRequest body or query parameters failed schema validation. Check the details array for specifics.
invalid_cursorThe pagination cursor is malformed or expired.
no_updatesPATCH request contained no fields to update.

401 Unauthorized

CodeMeaning
unauthorizedMissing Authorization header, invalid token, revoked API key, or expired API key.

403 Forbidden

CodeMeaning
forbiddenThe authenticated token lacks the required scope for this endpoint.

404 Not Found

CodeMeaning
not_foundThe requested resource does not exist or is not accessible to you.
board_not_foundThe board specified in the path does not exist or you do not own it.

429 Too Many Requests

CodeMeaning
rate_limit_exceededYou have exceeded the per-key or per-user rate limit. See the Retry-After header.

500 Internal Server Error

CodeMeaning
internal_errorAn unexpected server-side error. If this persists, contact support.

501 Not Implemented

CodeMeaning
not_implementedThe endpoint exists but the feature is not yet available.

503 Service Unavailable

CodeMeaning
service_unavailableA downstream service (e.g., embedding model) is unavailable. Retry after a few seconds.

Handling errors

const response = await fetch("https://api.chatgrid.ai/v1/boards", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  const error = await response.json();

  switch (error.status) {
    case 401:
      // Re-authenticate or refresh token
      break;
    case 429:
      const retryAfter = response.headers.get("Retry-After");
      // Wait and retry
      break;
    case 400:
      // Log validation details
      console.error("Validation errors:", error.details);
      break;
    default:
      console.error(`API error: ${error.code} - ${error.message}`);
  }
}