---
updatedAt: 2026-04-28T11:25:57.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.

# Search candidates

Searches candidates using filters and returns paginated results.

<ul>
  <li>Use the <code>fields</code> parameter to specify which fields to return</li>
  <li>Use the <code>filters</code> parameter to narrow down results</li>
  <li>Use cursor-based pagination with <code>limit</code> and <code>cursor</code></li>
</ul>

<p><b>Testing notes</b>:</p>
<ul>
  <li>Use the testing widget's <b>Try It!</b> option to test this endpoint.</li>
  <li>Use the <b>Examples > Request Example</b> option to see how to initiate body parameters.</li>
</ul>


# OpenAPI definition

```json
{
  "openapi": "3.1.1",
  "info": {
    "title": "Bob Hiring API",
    "description": "Public API for accessing Bob Hiring data including Job Openings, Candidates, and Applications.",
    "license": {
      "name": "Proprietary",
      "url": "https://apidocs.hibob.com/docs/api-terms-of-use"
    },
    "contact": {
      "name": "Hi Bob, Inc."
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.hibob.com/v1",
      "description": "Production"
    },
    {
      "url": "https://api.sandbox.hibob.com/v1",
      "description": "Sandbox"
    }
  ],
  "x-readme": {
    "metrics-enabled": false
  },
  "tags": [
    {
      "name": "Candidates",
      "description": "Search and retrieve candidate data"
    }
  ],
  "paths": {
    "/hiring/candidates/search": {
      "post": {
        "tags": [
          "Candidates"
        ],
        "operationId": "post_hiring-candidates-search",
        "summary": "Search candidates",
        "description": "Searches candidates using filters and returns paginated results.\n\n<ul>\n  <li>Use the <code>fields</code> parameter to specify which fields to return</li>\n  <li>Use the <code>filters</code> parameter to narrow down results</li>\n  <li>Use cursor-based pagination with <code>limit</code> and <code>cursor</code></li>\n</ul>\n\n<p><b>Testing notes</b>:</p>\n<ul>\n  <li>Use the testing widget's <b>Try It!</b> option to test this endpoint.</li>\n  <li>Use the <b>Examples > Request Example</b> option to see how to initiate body parameters.</li>\n</ul>\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CandidateSearchRequest"
              },
              "examples": {
                "basicSearch": {
                  "summary": "Basic search - all candidates",
                  "description": "Retrieve all candidates with core fields",
                  "value": {
                    "fields": [
                      "/candidate/id",
                      "/candidate/firstName",
                      "/candidate/lastName",
                      "/candidate/email",
                      "/candidate/phone"
                    ],
                    "filters": [],
                    "limit": 100
                  }
                },
                "filteredSearch": {
                  "summary": "Filter by email",
                  "description": "Search for candidates by email address",
                  "value": {
                    "fields": [
                      "/candidate/id",
                      "/candidate/firstName",
                      "/candidate/lastName",
                      "/candidate/email",
                      "/candidate/phone",
                      "/candidate/title",
                      "/candidate/socialMediaLinkedIn"
                    ],
                    "filters": [
                      {
                        "fieldId": "/candidate/email",
                        "operator": "equals",
                        "values": [
                          "jane.doe@example.com"
                        ]
                      }
                    ],
                    "limit": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved candidates",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Maximum requests per minute",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Remaining requests in current window",
                "schema": {
                  "type": "integer",
                  "example": 119
                }
              },
              "X-RateLimit-Reset": {
                "description": "Seconds until rate limit resets",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateSearchResponse"
                },
                "examples": {
                  "successResponse": {
                    "summary": "Successful response with candidates",
                    "value": {
                      "items": [
                        {
                          "/candidate/id": 7247347,
                          "/candidate/firstName": "Jane",
                          "/candidate/lastName": "Doe",
                          "/candidate/email": "jane.doe@example.com",
                          "/candidate/phone": "+1-555-0100",
                          "/candidate/title": "Senior Engineer",
                          "/candidate/socialMediaLinkedIn": "https://linkedin.com/in/janedoe"
                        }
                      ],
                      "response_metadata": {
                        "next_cursor": "eyJpZCI6NzI0NzM0OSwidHlwZSI6Im5leHRfcGFnZSJ9"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "INVALID_ARGUMENT",
                  "message": "Invalid field ID",
                  "requestId": "a1b2c3d4e5f6"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - IP not allowed or feature not enabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "FORBIDDEN",
                  "message": "Access denied: IP address is not allowed",
                  "requestId": "a1b2c3d4e5f6"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "RATE_LIMITED",
                  "message": "Rate limit exceeded. Try again in 45 seconds.",
                  "requestId": "a1b2c3d4e5f6"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "Basic": []
          },
          {
            "Bearer": []
          }
        ],
        "x-internal": false
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Basic": {
        "type": "http",
        "scheme": "basic",
        "description": "Basic HTTP authentication using service user credentials"
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "OAuth 2.0",
        "description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow <a href=\"https://apidocs.hibob.com/reference/oauth-20#testing-from-the-public-api-reference\" target=\"_blank\">these steps</a> to complete the OAuth 2.0 flow in Postman and then paste the token here."
      }
    },
    "schemas": {
      "CandidateSearchRequest": {
        "type": "object",
        "required": [
          "fields"
        ],
        "default": {
          "fields": [
            "/candidate/id",
            "/candidate/firstName",
            "/candidate/lastName",
            "/candidate/email",
            "/candidate/phone"
          ],
          "filters": [],
          "limit": 100
        },
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "/candidate/id",
                "/candidate/firstName",
                "/candidate/lastName",
                "/candidate/email",
                "/candidate/phone",
                "/candidate/title",
                "/candidate/address",
                "/candidate/photo",
                "/candidate/languages",
                "/candidate/skills",
                "/candidate/socialMedia",
                "/candidate/socialMediaLinkedIn",
                "/candidate/socialMediaFacebook",
                "/candidate/socialMediaInstagram",
                "/candidate/socialMediaThreads",
                "/candidate/socialMediaTwitter",
                "/candidate/socialMediaYouTube",
                "/candidate/socialMediaMedium",
                "/candidate/socialMediaGitHub",
                "/candidate/socialMediaReddit",
                "/candidate/socialMediaXing",
                "/candidate/socialMediaPersonalWebsite",
                "/candidate/country",
                "/candidate/city",
                "/candidate/region",
                "/candidate/education",
                "/candidate/experience",
                "/candidate/employeeId",
                "/candidate/externalUserId",
                "/candidate/importExternalId",
                "/candidate/sourceId",
                "/candidate/sourceEffectiveDate",
                "/candidate/sourceMismatchSeverity",
                "/candidate/extendConsentDueDate",
                "/candidate/extendedConsentRequestedAt",
                "/candidate/anonymizedAt",
                "/candidate/candidateConfirmedExtendedConsent",
                "/candidate/candidateNeedsToBeManuallyDeleted",
                "/candidate/jobOpeningsToApplicationIds",
                "/candidate/dataDownloadFileId",
                "/candidate/dataDownloadRequestedAt",
                "/candidate/dataDeletionRequestedAt",
                "/candidate/dataDownloadedAt",
                "/candidate/dataDeletionDate",
                "/candidate/sourceType",
                "/candidate/sourceApplicationId",
                "/candidate/sourceInstanceId",
                "/candidate/meetingBotEnabled",
                "/candidate/modificationDate"
              ]
            },
            "description": "Required list of field IDs to include in the response (1–50 fields). The property must be provided; if omitted or not provided, the API returns an error. You must explicitly choose which fields to fetch. For all available field IDs, see the <code>fields</code> object defined on each item in the 200 response schema."
          },
          "filters": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "fieldId",
                "operator",
                "values"
              ],
              "properties": {
                "fieldId": {
                  "type": "string",
                  "enum": [
                    "/candidate/id",
                    "/candidate/email",
                    "/candidate/firstName",
                    "/candidate/lastName",
                    "/candidate/modificationDate"
                  ],
                  "description": "Field ID to filter by"
                },
                "operator": {
                  "type": "string",
                  "enum": [
                    "equals",
                    "notEqual",
                    "greaterThan",
                    "lessThan"
                  ],
                  "description": "Filter operator. Use 'equals'/'notEqual' for exact matching. Use 'greaterThan'/'lessThan' for date range filtering (e.g. modificationDate).\n"
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": [
                      "string",
                      "number"
                    ]
                  }
                }
              }
            },
            "default": []
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 100
          },
          "cursor": {
            "type": "string"
          },
          "includeArchived": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "CandidateSearchResponseObject": {
        "type": "object",
        "description": "Flat key-value map where keys are field IDs (e.g. /candidate/firstName) and values are the field values directly. Only fields with values are included.\n",
        "properties": {
          "/candidate/id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for the candidate"
          },
          "/candidate/firstName": {
            "type": "string",
            "description": "First name"
          },
          "/candidate/lastName": {
            "type": "string",
            "description": "Last name"
          },
          "/candidate/email": {
            "type": "string",
            "format": "email",
            "description": "Email address"
          },
          "/candidate/phone": {
            "type": "string",
            "description": "Phone number"
          },
          "/candidate/title": {
            "type": "string",
            "description": "Professional title"
          },
          "/candidate/address": {
            "type": "string",
            "description": "Address"
          },
          "/candidate/photo": {
            "type": "object",
            "description": "Candidate photo data.",
            "properties": {
              "fileId": {
                "type": "integer",
                "description": "Internal file ID"
              },
              "url": {
                "type": "string",
                "description": "URL to the photo image"
              },
              "scanId": {
                "type": "string",
                "description": "Virus scan ID (UUID)"
              },
              "status": {
                "type": "string",
                "enum": [
                  "processing",
                  "processed",
                  "rejected",
                  "failed"
                ],
                "description": "Photo processing status"
              }
            }
          },
          "/candidate/languages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "/candidateLanguage/language": {
                  "type": "string",
                  "description": "Language code (e.g. en, he, es)"
                },
                "/candidateLanguage/proficiency": {
                  "type": "string",
                  "enum": [
                    "native",
                    "expert",
                    "advanced",
                    "upper intermediate",
                    "intermediate",
                    "foundational",
                    "beginner"
                  ],
                  "description": "Proficiency level. Possible values:<br /> <ul> <li><code>native</code> – Native</li> <li><code>expert</code> – Expert</li> <li><code>advanced</code> – Advanced</li> <li><code>upper intermediate</code> – Upper intermediate</li> <li><code>intermediate</code> – Intermediate</li> <li><code>foundational</code> – Foundational</li> <li><code>beginner</code> – Beginner</li> </ul>"
                }
              }
            },
            "description": "Languages spoken by the candidate"
          },
          "/candidate/skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "/candidateSkills/skillName": {
                  "type": "string",
                  "description": "Skill name"
                }
              }
            },
            "description": "Candidate skills"
          },
          "/candidate/socialMedia": {
            "type": "string",
            "description": "Social media URL (legacy field)"
          },
          "/candidate/socialMediaLinkedIn": {
            "type": "string",
            "description": "LinkedIn profile URL"
          },
          "/candidate/socialMediaFacebook": {
            "type": "string",
            "description": "Facebook profile URL"
          },
          "/candidate/socialMediaInstagram": {
            "type": "string",
            "description": "Instagram profile URL"
          },
          "/candidate/socialMediaThreads": {
            "type": "string",
            "description": "Threads profile URL"
          },
          "/candidate/socialMediaTwitter": {
            "type": "string",
            "description": "Twitter/X profile URL"
          },
          "/candidate/socialMediaYouTube": {
            "type": "string",
            "description": "YouTube channel URL"
          },
          "/candidate/socialMediaMedium": {
            "type": "string",
            "description": "Medium profile URL"
          },
          "/candidate/socialMediaGitHub": {
            "type": "string",
            "description": "GitHub profile URL"
          },
          "/candidate/socialMediaReddit": {
            "type": "string",
            "description": "Reddit profile URL"
          },
          "/candidate/socialMediaXing": {
            "type": "string",
            "description": "Xing profile URL"
          },
          "/candidate/socialMediaPersonalWebsite": {
            "type": "string",
            "description": "Personal website URL"
          },
          "/candidate/country": {
            "type": "string",
            "description": "Country"
          },
          "/candidate/city": {
            "type": "string",
            "description": "City"
          },
          "/candidate/region": {
            "type": "string",
            "description": "Region or state"
          },
          "/candidate/education": {
            "type": "array",
            "description": "Education history entries. Each item uses candidate education field IDs as keys.",
            "items": {
              "type": "object",
              "properties": {
                "/candidateEducation/school": {
                  "type": "string",
                  "description": "School or institution name"
                },
                "/candidateEducation/fieldOfStudy": {
                  "type": "string",
                  "description": "Field of study or major"
                },
                "/candidateEducation/degree": {
                  "type": "string",
                  "description": "Degree type (e.g. \"B.Sc\", \"M.A.\", \"Ph.D.\")"
                },
                "/candidateEducation/startDate": {
                  "type": "string",
                  "format": "date",
                  "description": "Start date (YYYY-MM-DD)"
                },
                "/candidateEducation/startDateDay": {
                  "type": "integer",
                  "description": "Day component of the start date"
                },
                "/candidateEducation/startDateMonth": {
                  "type": "integer",
                  "description": "Month component of the start date"
                },
                "/candidateEducation/startDateYear": {
                  "type": "integer",
                  "description": "Year component of the start date"
                },
                "/candidateEducation/endDate": {
                  "type": "string",
                  "format": "date",
                  "description": "End date (YYYY-MM-DD)"
                },
                "/candidateEducation/endDateDay": {
                  "type": "integer",
                  "description": "Day component of the end date"
                },
                "/candidateEducation/endDateMonth": {
                  "type": "integer",
                  "description": "Month component of the end date"
                },
                "/candidateEducation/endDateYear": {
                  "type": "integer",
                  "description": "Year component of the end date"
                }
              }
            }
          },
          "/candidate/experience": {
            "type": "array",
            "description": "Work experience entries. Each item uses candidate experience field IDs as keys.",
            "items": {
              "type": "object",
              "properties": {
                "/candidateExperience/title": {
                  "type": "string",
                  "description": "Job title"
                },
                "/candidateExperience/company": {
                  "type": "string",
                  "description": "Company name"
                },
                "/candidateExperience/industry": {
                  "type": "string",
                  "description": "Industry"
                },
                "/candidateExperience/summary": {
                  "type": "string",
                  "description": "Role description or summary"
                },
                "/candidateExperience/startDate": {
                  "type": "string",
                  "format": "date",
                  "description": "Start date (YYYY-MM-DD)"
                },
                "/candidateExperience/startDateDay": {
                  "type": "integer",
                  "description": "Day component of the start date"
                },
                "/candidateExperience/startDateMonth": {
                  "type": "integer",
                  "description": "Month component of the start date"
                },
                "/candidateExperience/startDateYear": {
                  "type": "integer",
                  "description": "Year component of the start date"
                },
                "/candidateExperience/endDate": {
                  "type": "string",
                  "format": "date",
                  "description": "End date (YYYY-MM-DD)"
                },
                "/candidateExperience/endDateDay": {
                  "type": "integer",
                  "description": "Day component of the end date"
                },
                "/candidateExperience/endDateMonth": {
                  "type": "integer",
                  "description": "Month component of the end date"
                },
                "/candidateExperience/endDateYear": {
                  "type": "integer",
                  "description": "Year component of the end date"
                },
                "/candidateExperience/isCurrent": {
                  "type": "boolean",
                  "description": "Whether this is the current position"
                },
                "/candidateExperience/durationDays": {
                  "type": "integer",
                  "description": "Duration in days (calculated from start/end dates)"
                }
              }
            }
          },
          "/candidate/employeeId": {
            "type": "string",
            "description": "Associated Bob employee ID (if the candidate was hired).<br /><br />To read this employee, use <a href=\"https://apidocs.hibob.com/reference/post_people-identifier\" target=\"_blank\">Read company employee fields by employee ID ↗</a>."
          },
          "/candidate/externalUserId": {
            "type": "string",
            "description": "External user ID"
          },
          "/candidate/importExternalId": {
            "type": "string",
            "description": "External ID from import"
          },
          "/candidate/sourceId": {
            "type": "string",
            "description": "Source identifier"
          },
          "/candidate/sourceEffectiveDate": {
            "type": "string",
            "format": "date-time",
            "description": "Effective date of the candidate source"
          },
          "/candidate/sourceMismatchSeverity": {
            "type": "string",
            "enum": [
              "none",
              "resolved",
              "low",
              "high"
            ],
            "description": "Severity level of source mismatch (if any). Possible values:<br /> <ul> <li><code>none</code> – None</li> <li><code>resolved</code> – Resolved</li> <li><code>low</code> – Low</li> <li><code>high</code> – High</li> </ul>"
          },
          "/candidate/extendConsentDueDate": {
            "type": "string",
            "format": "date-time",
            "description": "Due date for extended consent request"
          },
          "/candidate/extendedConsentRequestedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when extended consent was requested"
          },
          "/candidate/anonymizedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the candidate was anonymized"
          },
          "/candidate/candidateConfirmedExtendedConsent": {
            "type": "boolean",
            "description": "Whether the candidate confirmed extended consent"
          },
          "/candidate/candidateNeedsToBeManuallyDeleted": {
            "type": "boolean",
            "description": "Whether the candidate needs to be manually deleted"
          },
          "/candidate/jobOpeningsToApplicationIds": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "jobOpening": {
                  "type": "integer",
                  "description": "Job opening ID.<br /><br />To fetch the job opening, use <a href=\"https://apidocs.hibob.com/reference/post_hiring-job-openings-search\" target=\"_blank\">Search job openings ↗</a>."
                },
                "applicationIds": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  },
                  "description": "Application IDs for this job opening.<br /><br />To fetch applications, use <a href=\"https://apidocs.hibob.com/reference/post_hiring-applications-search\" target=\"_blank\">Search applications ↗</a>."
                }
              }
            },
            "description": "Mapping of job opening IDs to application IDs for this candidate.<br /><br />To fetch job openings, use <a href=\"https://apidocs.hibob.com/reference/post_hiring-job-openings-search\" target=\"_blank\">Search job openings ↗</a>. To fetch applications, use <a href=\"https://apidocs.hibob.com/reference/post_hiring-applications-search\" target=\"_blank\">Search applications ↗</a>."
          },
          "/candidate/dataDownloadFileId": {
            "type": "string",
            "description": "File ID for downloaded candidate data"
          },
          "/candidate/dataDownloadRequestedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when data download was requested"
          },
          "/candidate/dataDeletionRequestedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when data deletion was requested"
          },
          "/candidate/dataDownloadedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when data was downloaded"
          },
          "/candidate/dataDeletionDate": {
            "type": "string",
            "format": "date",
            "description": "Scheduled date for data deletion"
          },
          "/candidate/sourceType": {
            "type": "string",
            "enum": [
              "api",
              "api_internal",
              "free_job_board",
              "paid_job_board",
              "my_contracts_job_board",
              "referral",
              "agency",
              "agency_archived",
              "manual_upload",
              "custom_campaign",
              "custom_job_board",
              "custom_social",
              "referral_import",
              "referral_internal",
              "copied_from_job_opening",
              "sourced_by",
              "candidate_database",
              "opn_network"
            ],
            "description": "Sourcing channel type. Possible values:<br /> <ul> <li><code>api</code> – External Career page</li> <li><code>api_internal</code> – Internal Career page</li> <li><code>free_job_board</code> – Free job board</li> <li><code>paid_job_board</code> – Paid job board</li> <li><code>my_contracts_job_board</code> – My contracts job board</li> <li><code>referral</code> – Referral</li> <li><code>agency</code> – Agency</li> <li><code>agency_archived</code> – Agency (legacy)</li> <li><code>manual_upload</code> – Manual upload</li> <li><code>custom_campaign</code> – Custom Campaign</li> <li><code>custom_job_board</code> – Custom Job Board</li> <li><code>custom_social</code> – Social media</li> <li><code>referral_import</code> – Referral (import)</li> <li><code>referral_internal</code> – Referral internal</li> <li><code>copied_from_job_opening</code> – Copied from job opening</li> <li><code>sourced_by</code> – Sourced by</li> <li><code>candidate_database</code> – Candidate database</li> <li><code>opn_network</code> – OPN Network</li> </ul>"
          },
          "/candidate/sourceApplicationId": {
            "type": "number",
            "description": "Source application ID.<br /><br />To fetch the application, use <a href=\"https://apidocs.hibob.com/reference/post_hiring-applications-search\" target=\"_blank\">Search applications ↗</a>."
          },
          "/candidate/sourceInstanceId": {
            "type": "number",
            "description": "Source instance ID"
          },
          "/candidate/meetingBotEnabled": {
            "type": "boolean",
            "description": "Whether the meeting bot is enabled for this candidate"
          },
          "/candidate/modificationDate": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last modification to this candidate record"
          }
        }
      },
      "CandidateSearchResponse": {
        "type": "object",
        "required": [
          "items",
          "response_metadata"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CandidateSearchResponseObject"
            },
            "description": "Array of candidate objects"
          },
          "response_metadata": {
            "type": "object",
            "properties": {
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Cursor for next page. Null if no more results."
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "INVALID_ARGUMENT",
              "FORBIDDEN",
              "RATE_LIMITED",
              "INTERNAL_ERROR",
              "NOT_FOUND"
            ],
            "description": "Error code identifying the type of error:\n- `INVALID_ARGUMENT`: Invalid request parameters\n- `FORBIDDEN`: Access denied (IP not allowed or feature disabled)\n- `RATE_LIMITED`: Too many requests\n- `INTERNAL_ERROR`: Server-side error\n- `NOT_FOUND`: Resource not found\n"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "requestId": {
            "type": "string",
            "description": "Unique request identifier for tracking and debugging"
          }
        }
      }
    }
  }
}
```