Concepts

Error Handling

Understand the API error format, HTTP status codes, error code categories, and best practices for handling errors.

Error Response Format

All API errors follow a consistent JSON structure with a code (machine-readable identifier), message (human-readable explanation), and optional details object with additional context.

Response200 OK
{
  "error": {
    "code": "PROFILE_INCOMPLETE",
    "message": "Candidate profile is missing required fields: email, phone",
    "details": {
      "missingFields": ["email", "phone"]
    }
  }
}

HTTP Status Codes

200 — Success. 201 — Created (new resource). 204 — No Content (successful deletion). 400 — Bad Request (invalid input). 401 — Unauthorized (invalid API key). 403 — Forbidden (insufficient permissions). 404 — Not Found. 409 — Conflict (duplicate resource). 429 — Too Many Requests (rate limit exceeded). 500 — Internal Server Error. 503 — Service Unavailable.

Error Code Categories

Authentication: INVALID_API_KEY, API_KEY_REVOKED, UNAUTHORIZED. Validation: VALIDATION_ERROR, PROFILE_INCOMPLETE, INVALID_JOB_URL, INVALID_RESUME_FORMAT, RESUME_TOO_LARGE, MISSING_REQUIRED_FIELD, MAX_JOBS_EXCEEDED. Business Logic: INSUFFICIENT_CREDITS, DUPLICATE_APPLICATION, SESSION_ALREADY_ACTIVE, ATS_NOT_SUPPORTED, USER_TOTAL_LIMIT_REACHED, USER_MONTHLY_LIMIT_REACHED. Processing: RESUME_DOWNLOAD_FAILED, ATS_BLOCKED, WORKER_TIMEOUT, FORM_FILL_FAILED.

Error Handling Example

Here's how to handle common error scenarios in your integration.

# Check HTTP status code and parse error response
curl -s -w "\n%{http_code}" -X POST https://apply-api.boringproject.ai/api/v1/sessions/apply \
  -H "Authorization: Bearer bp_live_..." \
  -H "Content-Type: application/json" \
  -d '{...}'

# Error responses follow the format:
# { "error": { "code": "ERROR_CODE", "message": "Human-readable message" } }

Related docs

Continue reading

Rate Limiting

Understand API rate limits, response headers, and how to handle 429 responses gracefully with exponential backoff.

Authentication

Authenticate requests to the Boring Project API using Bearer tokens with your API key.

Idempotency

Prevent duplicate operations by including an Idempotency-Key header in POST requests.