Error Handling
The Fribl API uses standard HTTP status codes and returns JSON error bodies to indicate what went wrong.
All error responses follow this structure:
{
"error": "Human-readable error description"
}
HTTP status codes
| Code | Meaning | When it occurs |
|---|
200 | OK | Request succeeded |
400 | Bad Request | Invalid request body, missing required fields, invalid file format, or weight sum exceeds 1.0 |
401 | Unauthorized | Missing or invalid X-API-KEY header |
404 | Not Found | Requested CV, job, or match does not exist |
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.
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. Each task moves through these statuses:
| Status | Meaning |
|---|
PENDING | Task has been created and is queued for processing |
PROCESSING | Document is actively being analyzed |
COMPLETED | Analysis is finished — retrieve results or run matching |
FAILED | Analysis failed — resubmit the document |
Poll the status endpoint at reasonable intervals (e.g., every 2–3 seconds) rather than in a tight loop. Typical analysis completes within a few seconds.
