Skip to main content
RequestHuntRequestHunt

Error Handling

The API uses standard HTTP status codes and returns detailed error information in the response body.

Error Response Format

All errors follow this consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Error Codes

HTTP StatusCodeDescription
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENAPI key does not have permission for this action
404NOT_FOUNDResource not found
400BAD_REQUESTInvalid request parameters
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORInternal server error

401 Unauthorized

Missing or invalid API key. Make sure you're including the key in the Authorization header.

Example
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

400 Bad Request

Invalid request parameters. Check the parameter types and values.

Example
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid platform 'tiktok'. Valid platforms: x, reddit, github, youtube, linkedin, amazon"
  }
}

429 Rate Limited

You've exceeded your rate limit. Wait for the reset time or upgrade your plan.

Example
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Realtime rate limit exceeded (500/month). Resets on 2025-01-01."
  }
}

500 Internal Error

Something went wrong on our end. If this persists, please contact support.

Example
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to fetch requests"
  }
}

Handling Errors

Best practices for handling API errors:

  • Always check the HTTP status code first
  • Parse the error.code field for programmatic handling
  • Display error.message to users for context
  • Implement exponential backoff for 429 errors
  • Log 500 errors and report if persistent