Errors

All errors return a JSON body with a detail field. Application-level validation (400) and internal failures (500) return a structured { status, message } object. Auth and rate-limit errors return a plain string. Schema-level validation failures (422) return an array of field-by-field error entries.

Quick reference

Status	detail.status	Endpoints
400	NO_COMPANIES_PROVIDED	POST /v1/company/enrich
400	NO_PERSONS_PROVIDED	POST /v1/person/enrich
400	NO_FIELDS_PROVIDED	POST /v1/company/enrich, POST /v1/person/enrich
401	—	all authenticated endpoints
422	— (array of field errors)	all authenticated endpoints
403	—	GET /v1/prospecting/jobs/{id}, GET /v1/prospecting/jobs/{id}/results — job belongs to a different tenant
404	—	GET /v1/prospecting/jobs/{id}, GET /v1/prospecting/jobs/{id}/results — job not found
429	—	all endpoints except /health
500	ENRICHMENT_FAILED	POST /v1/company/enrich, POST /v1/person/enrich
500	GET_SIGNALS_FAILED	POST /v1/signals/get-signals
502	PHOENIX_UPSTREAM_ERROR	POST /v1/prospecting/start, GET /v1/prospecting/jobs/{id}, GET /v1/prospecting/jobs/{id}/results — upstream prospecting service error
504	—	all /v1/prospecting/* endpoints — upstream prospecting service timeout

400 Bad Request

Returned when the request body is missing required fields.

{
  "detail": {
    "status": "NO_COMPANIES_PROVIDED",
    "message": "At least one company identifier must be provided"
  }
}

{
  "detail": {
    "status": "NO_PERSONS_PROVIDED",
    "message": "At least one person identifier must be provided"
  }
}

{
  "detail": {
    "status": "NO_FIELDS_PROVIDED",
    "message": "Provide at least one field name in 'fields', set 'include_metadata' to true, or provide 'allow_signals'"
  }
}

401 Unauthorized

Returned when the X-Api-Key header is missing or invalid.

{ "detail": "Invalid API key" }

422 Unprocessable Entity

Returned when the request body fails Pydantic / FastAPI schema validation — for example, a missing required field, a type mismatch, an enum value outside the allowed set, or an identifier object that fails its model_validator (e.g. a CompanyIdentifier with none of website, linkedin_url, or linkedin_id).

The response body conforms to HTTPValidationError: detail is an array of ValidationError entries pinpointing each offending field with a JSON-pointer-style loc, a human-readable msg, and a Pydantic error type.

{
  "detail": [
    {
      "loc": ["body", "companies", 0],
      "msg": "Value error, At least one identifier (website, linkedin_url, or linkedin_id) must be provided",
      "type": "value_error"
    },
    {
      "loc": ["body", "allow_signals", "type"],
      "msg": "Input should be 'new_hire', 'Key Changes', 'Account Visitor', ...",
      "type": "enum"
    }
  ]
}

400 vs 422 — 400 is returned by application-level checks inside the endpoint handler (e.g. empty companies list). 422 is returned by FastAPI before the handler runs, when the JSON itself doesn’t match the request schema.

429 Too Many Requests

Returned when a rate limit is exceeded (burst window or per-second cap).

{ "detail": "Rate limit exceeded" }

The /health endpoint is exempt from rate limiting.

500 Internal Server Error

Returned when the service itself fails. Usually transient — retry with exponential backoff.

{
  "detail": {
    "status": "ENRICHMENT_FAILED",
    "message": "An error occurred while processing the request"
  }
}

{
  "detail": {
    "status": "GET_SIGNALS_FAILED",
    "message": "An error occurred while fetching signals"
  }
}

If a 500 persists for more than a minute, contact support@onfire.ai with:

• Your tenant name.
• The timestamp (UTC) of the request.
• The exact request body.
• The response body you received.