Error Handling

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": [
    {
      "type": "missing",
      "loc": ["query", "since"],
      "msg": "Field required",
      "input": null
    }
  ]
}

// 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

A hand-rolled request error — for example, an unparseable date on GET /v2/jobs/expired-jobs or an invalid search_type on vector search. Most field and type mismatches return 422 instead (see below).

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 JSON or query parameters, but failed Pydantic validation (wrong type, missing required field, invalid enum value, etc.). This is FastAPI’s default for request-body and query-parameter 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 v2 field errors under detail:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "since"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Other common shapes:

{
  "detail": [
    {
      "type": "list_type",
      "loc": ["body", "job_titles"],
      "msg": "Input should be a valid list",
      "input": "not-a-list"
    }
  ]
}

{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "visa"],
      "msg": "Input should be a valid string",
      "input": true
    }
  ]
}

Custom validators (e.g. an invalid job_category) return type: "value_error" and may include a ctx object:

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "job_category"],
      "msg": "Value error, job_category must be a list of strings from the valid list of job categories. ...",
      "input": ["Not A Real Category"],
      "ctx": { "error": {} }
    }
  ]
}

Each object includes:

type — machine-readable error category (e.g. missing, list_type, string_type, value_error).
loc — path to the offending field (e.g. ["query", "since"] or ["body", "visa"]).
msg — human-readable explanation.
input — the value that was rejected (may be null for missing fields).
ctx — optional extra context on some value_error responses.

Authentication Errors (401)

Missing key on page 2+:

{ "detail": "Sign in to view results beyond the first page" }

Missing key on an endpoint that always requires auth:

{ "detail": "Sign in to access this endpoint" }

Invalid or revoked key:

{ "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

Implement Retry Logic

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));
    }
  }
};

Validate User Input

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;
};

Centralize Error Handling

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

400 vs 422: Field and type validation failures (missing required params, wrong JSON types, invalid enum values) return 422 — FastAPI’s default. 400 is reserved for a small set of hand-rolled checks, such as an unparseable since date on expired jobs or an invalid search_type on vector search.

Error	Possible Cause	Solution
400 Bad Request	Hand-rolled check failed (e.g. unparseable date)	Read the `detail` string; fix the specific value called out
401 Unauthorized	Invalid or expired API key	Verify your API key is correct and not expired
404 Not Found	Job or company ID doesn’t exist	Verify the ID is correct and the resource exists
422 Unprocessable Entity	Validation error in request data	Check the error details for specific field issues
429 Too Many Requests	Rate limit exceeded	Implement rate limiting and retry with backoff
500 Internal Server Error	Server-side issue	Contact support with the error details and timestamp

Getting Help

If you encounter persistent errors or need additional assistance:

Check if the error message provides clear instructions on how to fix the issue
Consult the documentation for the specific endpoint you’re using
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

Jobs API

Hiring Manager API

Companies API

Insights API

Reference Data API

Resumes

Tasks API

Error Handling

Error Response Format

Common Status Codes

Detailed Error Types

Validation Errors (422)

Authentication Errors (401)

Rate Limiting Errors (429)

Error Handling Best Practices

Common Error Scenarios and Solutions

Getting Help

​Error Response Format

​Common Status Codes

​Detailed Error Types

​Validation Errors (422)

​Authentication Errors (401)

​Rate Limiting Errors (429)

​Error Handling Best Practices

​Common Error Scenarios and Solutions

​Getting Help

Error Response Format

Common Status Codes

Detailed Error Types

Validation Errors (422)

Authentication Errors (401)

Rate Limiting Errors (429)

Error Handling Best Practices

Common Error Scenarios and Solutions

Getting Help