Error Handling
The Fribl API uses standard HTTP status codes and returns JSON error bodies to indicate what went wrong.
Most API errors follow this structure:
{
"error": "Human-readable error description"
}
{
"detail": {
"message": "Update validation failed.",
"invalid_skills": [
{
"id": "not-a-real-skill-id",
"field": "hard_skills",
"message": "Skill does not exist in the canonical graph/taxonomy."
}
]
}
}
422 Unprocessable Entity with structured details:
{
"detail": {
"message": "Payload does not match VacancyUpdate schema for entity_type=Vacancy.",
"schema": "VacancyUpdate",
"errors": [
{
"type": "missing",
"loc": ["information", "title"],
"msg": "Field required"
}
]
}
}
HTTP status codes
| Code | Meaning | When it occurs |
|---|
200 | OK | Request succeeded |
400 | Bad Request | Invalid request body, missing required fields, invalid file format, weight sum exceeds 1.0, or update validation failed |
401 | Unauthorized | Missing or invalid x-api-key header |
404 | Not Found | Requested CV, job, or match does not exist |
422 | Unprocessable Entity | Update payload does not match the expected CV or job update schema |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Unexpected server-side failure |
502 | Bad Gateway | Upstream service error (sourcing endpoints) |
503 | Service Unavailable | Required external service is not configured (sourcing endpoints) |
Common error examples
Invalid API key
{
"error": "Invalid API Key."
}
x-api-key header contains a valid key.
Missing required field
{
"error": "Missing required fields."
}
inputs field must be a non-empty array of strings.
Update validation failure
{
"detail": {
"message": "content_language is required and must be a valid ISO 639-1 language code."
}
}
PUT /jobs/{id} and PUT /cvs/{id}, always send content_language and use split hard_skills / soft_skills arrays with canonical lowercase relationship values: required, optional, satisfies.
Resource not found
{
"error": "CV not found"
}
Match weight validation
{
"error": "Sum of weights cannot be greater than 1"
}
experience + hardSkills + softSkills + education in your weights object does not exceed 1.0.
Processing statuses
CV and job analysis is asynchronous. After submitting a document, poll the status endpoint to track progress. The batch status endpoints can return these per-item statuses:
| Status | Meaning |
|---|
in_progress | Document is actively being analyzed |
retrying | A transient failure occurred and the job is being retried automatically |
completed | Analysis is finished — retrieve results or run matching |
failed | Analysis failed — resubmit the document |
not_found | No status record exists for that ID in the requested resource type |
Poll the status endpoint at reasonable intervals (e.g., every 2–3 seconds) rather than in a tight loop. Continue polling while the status is in_progress or retrying. Typical analysis completes within a few seconds.
