Error Handling
Every API error is JSON, safe to show to an operator, and traceable with a request ID. Keep your API key out of logs.
Authorization: Bearer <your-api-key>; do not send a Clerk browser session token to an API-key endpoint.Stable Error Response
{
"error": "Invalid or missing API key",
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key",
"request_id": "req_abc123",
"timestamp": "2026-08-29T12:00:00.000Z",
"documentation_url": "https://search.venym.io/docs/errors"
}codeMachine-readable category such as UNAUTHORIZED or RATE_LIMITED.
request_idTrace identifier to include in a support request.
timestampISO 8601 time at which the error was created.
documentation_urlCanonical documentation for the error contract.
HTTP Status Codes
INVALID_JSONThe request body is not valid JSON. Use double-quoted keys and strings.
BAD_REQUESTThe JSON body is valid JSON, but one of its values failed validation.
UNAUTHORIZEDThe Authorization header is missing or the API key is invalid.
INSUFFICIENT_CREDITSThe account balance is below the required reservation.
FORBIDDENThe requested plan-gated feature is unavailable.
RATE_LIMITEDThe endpoint window is exhausted; honor Retry-After.
INTERNAL_ERRORAn unexpected failure occurred; retain request_id for support.
Handle Errors Safely
response=$(curl -sS -D /tmp/venym-headers \
-X POST https://search.venym.io/api/v1/search \
-H "Authorization: Bearer $VENYM_SEARCH_API_KEY" \
-H "Content-Type: application/json" \
--data '{"query":"latest news","max_results":5}')
printf '%s\n' "$response" | jq .Do not retry 400, 401, 402, or 403 without changing the request or account. Retry transient 429 and 5xx responses with bounded backoff.