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

success

The request was successful.

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).

error

Authentication is required or the provided credentials are invalid.

error

The authenticated user does not have permission to access the requested resource, or the endpoint’s feature is not on the account’s plan (X-Billing-Code: feature_missing).

error

The requested resource does not exist.

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.

error

Either the request rate limit (100 per 60 s per key, Retry-After present) or a plan quota (X-Billing-Code: limit_exceeded). See Rate Limiting and Quota below — only the first should be retried.

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)

All data endpoints require authentication on every request. Missing key/header on most endpoints:

{ "detail": "Missing authorization header" }

Missing key on certain endpoints (expired jobs, exports, insights):

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

Invalid or revoked key:

{ "detail": "Invalid API key" }

"Sign in to access this endpoint" 401s also carry the header X-Billing-Code: auth_required — branch on that instead of string-matching detail. ("Missing authorization header" responses do not include it.)

Feature Errors (403)

An API key whose plan does not include the endpoint’s feature gets a 403 with X-Billing-Code: feature_missing:

{ "detail": "Your current plan does not include access to this endpoint. Upgrade at /v2/billing/portal." }

Every plan, including Free, includes the job, company, vector, export, and insights endpoints; this applies to add-on features such as hiring-manager contacts.

Rate Limiting Errors (429)

API traffic is rate-limited per API key: 100 requests per 60 seconds. (Anonymous requests to data endpoints are rejected with 401 before rate limiting; the 25-per-60-seconds per-IP limit applies only to public reference and marketing endpoints.) All responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; when you exceed the limit, the 429 includes a Retry-After header (seconds):

{ "detail": "Rate limit exceeded. Try again in 39s. Limit is 100 requests per 60s per user." }

Quota Errors (429)

A different 429 — with header X-Billing-Code: limit_exceeded — means you’ve exhausted your plan’s included usage for a meter this billing period:

{ "detail": "You've reached your plan's included usage of 25000 for this period. Upgrade at /v2/billing/portal to continue." }

The check runs before the request executes, using the most it could cost (the requested limit on per-result endpoints). When that does not fit in the remaining allowance, the same 429 tells you how many units are left so you can retry with a smaller limit:

{ "detail": "This request could use up to 100 jobs but only 2 of your plan's included 500 remain this period. Lower `limit` or upgrade at /v2/billing/portal." }

Do not retry quota 429s with backoff — the answer will not change until the period resets or the plan is upgraded. Distinguish the two by X-Billing-Code (quota) vs Retry-After (rate limit). Quota 429s also include the full set of usage headers so you can see which meter is exhausted and when the period resets.

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) {
        if (response.headers.get('x-billing-code') === 'limit_exceeded') {
          // Plan quota, not a rate limit: retrying will not help
          throw new Error(`Quota exhausted: ${(await response.json()).detail}`);
        }
        // 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 (`Retry-After`)	Implement rate limiting and retry with backoff
429 Too Many Requests	Plan quota exhausted (`X-Billing-Code: limit_exceeded`)	Lower `limit` to the remaining units, wait for the period reset, or upgrade — do not retry with backoff
403 Forbidden	Feature not on plan (`X-Billing-Code: feature_missing`)	Upgrade the plan or use an included endpoint
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

Expired Jobs API

Hiring Manager API

Companies API

Insights API

Salary Benchmark API

Reference Data API

Resumes

Tasks API

Billing & Usage

Error Handling

Error Response Format

Common Status Codes

Detailed Error Types

Validation Errors (422)

Authentication Errors (401)

Feature Errors (403)

Rate Limiting Errors (429)

Quota 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)

​Feature Errors (403)

​Rate Limiting Errors (429)

​Quota 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)

Feature Errors (403)

Rate Limiting Errors (429)

Quota Errors (429)

Error Handling Best Practices

Common Error Scenarios and Solutions

Getting Help