Skip to main content
This page describes the error responses you might encounter when using the Hirebase API and how to handle them.

​
Error Response Format

All error responses from the Hirebase API follow a consistent format: 
{
  "error": "Error Type",
  "message": "A human-readable description of what went wrong",
  "details": {
    // Optional additional context about the error
  }
}

​
Common Status Codes

​
200 OK
success
The request was successful.
​
400 Bad Request
error
The request was malformed or contained invalid parameters.
​
401 Unauthorized
error
Authentication is required or the provided credentials are invalid.
​
403 Forbidden
error
The authenticated user does not have permission to access the requested resource.
​
404 Not Found
error
The requested resource does not exist.
​
422 Unprocessable Entity
error
The request was well-formed but contains semantic errors or validation failures.
​
429 Too Many Requests
error
The client has sent too many requests in a given amount of time (rate limiting).
​
500 Internal Server Error
error
Something went wrong on the server side. These errors should be reported to the Hirebase team.

​
Detailed Error Types

​
Validation Errors

When a request fails validation, the API returns a 422 Unprocessable Entity status code with details about the validation failures: 
{
  "error": "Validation Error",
  "message": "The request contains invalid fields",
  "details": {
    "fields": {
      "job_titles": "Must be an array of strings",
      "salary": {
        "min": "Must be a positive number",
        "max": "Must be greater than min"
      }
    }
  }
}

​
Authentication Errors

When authentication fails, you’ll typically see: 
{
  "error": "Authentication Error",
  "message": "Invalid API key or session expired"
}

​
Rate Limiting Errors

When you’ve exceeded your rate limit: 
{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded the allowed request rate",
  "details": {
    "rate_limit": "100 requests per minute",
    "retry_after": 30
  }
}
The retry_after field indicates the number of seconds to wait before retrying the request.

​
Error Handling Best Practices

For transient errors (such as rate limiting or temporary server issues), implement an exponential backoff retry mechanism:
const fetchWithRetry = async (url, options, maxRetries = 3) => {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - get retry-after header
        const retryAfter = response.headers.get('retry-after') || 1;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        retries++;
        continue;
      }
      
      return response;
    } catch (error) {
      retries++;
      if (retries >= maxRetries) throw error;
      
      // Exponential backoff
      await new Promise(r => setTimeout(r, Math.pow(2, retries) * 1000));
    }
  }
};
Before sending requests to the API, validate user input on the client side to catch common issues:
const validateSalaryRange = (min, max) => {
  if (min && isNaN(min)) {
    throw new Error("Minimum salary must be a number");
  }
  
  if (max && isNaN(max)) {
    throw new Error("Maximum salary must be a number");
  }
  
  if (min && max && parseInt(min) > parseInt(max)) {
    throw new Error("Maximum salary must be greater than minimum salary");
  }
  
  return true;
};
Create a central error handling system in your application to process API errors consistently:
const handleApiError = (error) => {
  if (error.status === 401) {
    // Redirect to login
    redirectToLogin();
    return;
  }
  
  if (error.status === 429) {
    // Show rate limit message
    showNotification("You've made too many requests. Please try again later.");
    return;
  }
  
  // Handle other error types
  showErrorMessage(error.message || "An unexpected error occurred");
  
  // Log error for debugging
  console.error("API Error:", error);
};

​
Common Error Scenarios and Solutions

ErrorPossible CauseSolution
400 Bad RequestMalformed JSON or query parametersDouble-check your request format and parameters
401 UnauthorizedInvalid or expired API keyVerify your API key is correct and not expired
404 Not FoundJob or company ID doesn’t existVerify the ID is correct and the resource exists
422 Unprocessable EntityValidation error in request dataCheck the error details for specific field issues
429 Too Many RequestsRate limit exceededImplement rate limiting and retry with backoff
500 Internal Server ErrorServer-side issueContact support with the error details and timestamp

​
Getting Help

If you encounter persistent errors or need additional assistance:
  1. Check if the error message provides clear instructions on how to fix the issue
  2. Consult the documentation for the specific endpoint you’re using
  3. Contact support at spencer@hirebase.org with:
    • The full error message and status code
    • The endpoint you were trying to access
    • A sample of your request (with sensitive data removed)
    • Timestamp of when the error occurred