Skip to main content

​
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

{
  "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" }
  ]
}
FieldTypeDescription
statusCodeintegerHTTP status code
errorstringShort HTTP reason phrase (e.g. "Bad Request")
messagestringHuman-readable summary of the failure
pathstringThe request path that triggered the error
requestIdstringUUID for this request — include this when contacting support
timestampstringISO 8601 timestamp of when the error occurred
errorsarrayPresent 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. 
// 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:
FieldTypeDescription
propertystringThe request body field that failed
messagestringWhat 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.
{
  "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.
{
  "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.
{
  "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.
{
  "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.
{
  "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 for details.
{
  "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.
{
  "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

StatusMeaningRetry?
400Validation failed — fix the errorsNo — fix the request first
401Invalid or missing credentialsNo — refresh your credentials
402Insufficient creditsNo — top up your balance
403No organization contextNo — check your credential setup
404Resource not foundNo
429Rate limit exceededYes — after exponential backoff
500 / 503Server errorYes — 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. 
# 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