Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 FastAPI’s standard shape — a single top-level detail field. For most errors detail is a string; for request-validation errors (422) it is an array of field-level error objects. 
// 401 Unauthorized
{ "detail": "Invalid API key" }

// 422 Unprocessable Entity (validation error)
{
  "detail": [
    {
      "loc": ["body", "salary", "min"],
      "msg": "ensure this value is greater than or equal to 0",
      "type": "value_error.number.not_ge"
    }
  ]
}

// 429 Too Many Requests
{ "detail": "Rate limit exceeded. Please try again later." }
Read error messages from response.detail — not response.error or response.message. There is no top-level error or message field.

​
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 (422)

When a request fails validation, the API returns a 422 Unprocessable Entity with an array of Pydantic-style field errors under detail: 
{
  "detail": [
    {
      "loc": ["body", "salary", "min"],
      "msg": "ensure this value is greater than or equal to 0",
      "type": "value_error.number.not_ge"
    },
    {
      "loc": ["body", "job_titles"],
      "msg": "value is not a valid list",
      "type": "type_error.list"
    }
  ]
}
Each object includes:
  • loc — path to the offending field (e.g., ["body", "salary", "min"]).
  • msg — human-readable explanation.
  • type — machine-readable error category.

​
Authentication Errors (401)

{ "detail": "Missing authorization header" }

{ "detail": "Invalid API key" }

​
Rate Limiting Errors (429)

{ "detail": "Rate limit exceeded. Please try again later." }
Most search endpoints are rate-limited at 4 requests per second. Back off and retry with exponential delay.

​
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