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" }
  ]
}

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.

// 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

400 Bad Request — validation failure

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" }
  ]
}

401 Unauthorized — missing or invalid credentials

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"
}

402 Payment Required — insufficient credits

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"
}

403 Forbidden — missing organization context

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"
}

404 Not Found — operation or resource not found

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"
}

429 Too Many Requests — rate limit hit

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"
}

500 / 503 — server-side failure

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

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.

# 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

Get Started

Core Concepts

Guides

Reference

Error handling

Error Handling and HTTP Status Codes

Standard error body

Validation errors (400)

HTTP status codes

Quick reference

Using `requestId` for support

​Error Handling and HTTP Status Codes

​Standard error body

​Validation errors (400)

​HTTP status codes

​Quick reference

​Using requestId for support

Error Handling and HTTP Status Codes

Standard error body

Validation errors (400)

HTTP status codes

Quick reference

Using `requestId` for support