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 aDocumentation Index
Fetch the complete documentation index at: https://docs.thehog.ai/llms.txt
Use this file to discover all available pages before exploring further.
requestId you can share with support to pinpoint the exact failed call.
Standard error body
| 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-levelmessage is "Validation failed" and the errors array lists every field that failed, along with a plain-English description of the constraint that was violated.
errors array has two fields:
| Field | Type | Description |
|---|---|---|
property | string | The request body field that failed |
message | string | What constraint was violated |
errors before retrying — the request will continue to fail until all validation rules pass.
HTTP status codes
400 Bad Request — validation failure
400 Bad Request — validation failure
Your request body contains missing or invalid fields. The
errors array lists every violation. Fix each field and retry.401 Unauthorized — missing or invalid token
401 Unauthorized — missing or invalid token
402 Payment Required — insufficient credits
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 (use an
/estimate endpoint to preview cost first).403 Forbidden — missing organization context
403 Forbidden — missing organization context
The token is valid but The Hog cannot determine which organization the request belongs to. This usually means the token carries no organization claim. Check your authentication setup and ensure the correct organization is set in your token or API key configuration.
404 Not Found — operation or resource not found
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.
429 Too Many Requests — rate limit hit
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.
500 / 503 — server-side failure
500 / 503 — server-side failure
An unexpected error occurred on The Hog’s servers. The
message is intentionally generic in production — no internal details are exposed. These errors are logged automatically. If they persist, contact support with your requestId.Quick reference
| Status | Meaning | Retry? |
|---|---|---|
| 400 | Validation failed — fix the errors | No — fix the request first |
| 401 | Invalid or missing token | No — refresh your credentials |
| 402 | Insufficient credits | No — top up your balance |
| 403 | No organization context | No — check your token 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 context — inputs, provider responses, and timing — without needing you to reproduce the issue.