> ## Documentation Index > Fetch the complete documentation index at: https://docs.thehog.ai/llms.txt > Use this file to discover all available pages before exploring further. # Error handling # Error Handling and HTTP Status Codes > The Hog returns RFC 7807-style JSON error bodies for all failures. Learn the error shape, status codes, validation errors, and how to handle them. When a request fails, The Hog API always returns a structured JSON body — never a bare string or an empty response. Every error body follows the same shape so you can handle failures consistently in your code, and every error includes a `requestId` you can share with support to pinpoint the exact failed call. ## Standard error body ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 400, "error": "Bad Request", "message": "Validation failed", "path": "/api/v1/people/search", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-03-12T12:00:00.000Z", "errors": [ { "property": "query", "message": "query must be a string" } ] } ``` | Field | Type | Description | | ------------ | ------- | ------------------------------------------------------------ | | `statusCode` | integer | HTTP status code | | `error` | string | Short HTTP reason phrase (e.g. `"Bad Request"`) | | `message` | string | Human-readable summary of the failure | | `path` | string | The request path that triggered the error | | `requestId` | string | UUID for this request — include this when contacting support | | `timestamp` | string | ISO 8601 timestamp of when the error occurred | | `errors` | array | Present only on 400 validation failures — see below | ## Validation errors (400) When your request body fails validation, the top-level `message` is `"Validation failed"` and the `errors` array lists every field that failed, along with a plain-English description of the constraint that was violated. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} // HTTP 400 — validation failure { "statusCode": 400, "error": "Bad Request", "message": "Validation failed", "path": "/api/v1/people/search", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z", "errors": [ { "property": "query", "message": "query must be a string" }, { "property": "limit", "message": "limit must not be greater than 100" } ] } ``` Each object in the `errors` array has two fields: | Field | Type | Description | | ---------- | ------ | ---------------------------------- | | `property` | string | The request body field that failed | | `message` | string | What constraint was violated | Fix every entry in `errors` before retrying — the request will continue to fail until all validation rules pass. ## HTTP status codes Your request body contains missing or invalid fields. The `errors` array lists every violation. Fix each field and retry. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 400, "error": "Bad Request", "message": "Validation failed", "path": "/api/v1/companies/search", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z", "errors": [ { "property": "filters.headcount", "message": "headcount must be a positive number" } ] } ``` The `X-Access-Key` or `X-Secret-Key` header was not provided, or the credential pair is invalid or revoked. Verify both values from the Credentials page. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 401, "error": "Unauthorized", "message": "Invalid or missing authentication credentials", "path": "/api/v1/companies/search", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z" } ``` Your organization does not have enough credits to complete the request. Top up your balance or reduce the scope of the request. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 402, "error": "Payment Required", "message": "Insufficient credits to complete this request", "path": "/api/deep-research", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z" } ``` The credentials are valid but The Hog cannot determine which organization the request belongs to. Check that you are using a dashboard-created API key and API secret for the intended organization. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 403, "error": "Forbidden", "message": "No organization context found", "path": "/api/enrichments", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z" } ``` The operation ID or resource you requested does not exist or does not belong to your organization. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 404, "error": "Not Found", "message": "Operation not found", "path": "/api/operations/op_nonexistent", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z" } ``` Your organization has exceeded the allowed request rate. Wait before retrying and use exponential backoff. See [Rate Limits](/reference/rate-limits) for details. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded. Please slow down and retry.", "path": "/api/operations/op_01HZ9K2QW3RV4M5N6P7Q8R9S0T", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z" } ``` An unexpected error occurred on The Hog's servers. The `message` is intentionally generic in production. These errors are logged automatically. If they persist, contact support with your `requestId`. ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "statusCode": 500, "error": "Internal Server Error", "message": "An unexpected error occurred", "path": "/api/enrichments", "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a", "timestamp": "2025-06-10T09:14:33.000Z" } ``` ## Quick reference | Status | Meaning | Retry? | | --------- | ------------------------------------ | -------------------------------- | | 400 | Validation failed — fix the `errors` | No — fix the request first | | 401 | Invalid or missing credentials | No — refresh your credentials | | 402 | Insufficient credits | No — top up your balance | | 403 | No organization context | No — check your credential setup | | 404 | Resource not found | No | | 429 | Rate limit exceeded | Yes — after exponential backoff | | 500 / 503 | Server error | Yes — after a short wait | ## Using `requestId` for support Every error body includes a `requestId` field. When you open a support ticket or file a bug report, always include this value. It maps directly to a specific request in The Hog's logs, so the support team can retrieve the full request context without needing you to reproduce the issue. ```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}} # The requestId is in the error body AND the X-Request-Id response header curl -i -X POST https://developer.thehog.ai/api/v1/companies/search \ -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \ -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"query": "acme"}' # Look for: X-Request-Id: 3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a ```