Errors

Fontes Portal API returns errors in ProblemDetails format, as defined by RFC 9457. Every error response has Content-Type: application/problem+json.

Response shape

{
  "type": "https://api.fontes.ee/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "traceId": "00-4af4b5c6d7e8f9a0b1c2d3e4f5a6b7c8-1234567890abcdef-00",
  "errors": [
    {
      "code": "validation_failed",
      "field": "rows[0].jobFamilyCode",
      "message": "Job family code 'JF999' is not in the catalog."
    }
  ]
}
Field Description
type URI that uniquely identifies the error type. Stable — safe to match in code.
title Human-readable summary of the error type.
status HTTP status code (mirrors the response status).
detail Human-readable explanation of this specific occurrence.
traceId Correlation ID for this request. Always log this — Fontes support uses it to trace your request in server logs.
errors Array of structured error entries (present on validation errors; may be absent on other error types).

Error codes

HTTP Code Title Description
400 idempotency_key_required Idempotency-Key required This endpoint requires the Idempotency-Key header.
400 validation_failed Validation failed One or more fields failed validation.
401 unauthorized Unauthorized Invalid or missing credentials.
403 forbidden Forbidden The authenticated client does not have permission for this resource.
404 customer_not_found Customer not found No customer matches the supplied registry number.
422 idempotency_key_reused Idempotency-Key reused with different body Re-using an Idempotency-Key requires an identical request body. Mint a new key for new logical submissions.
422 no_eligible_survey No eligible survey The customer has no survey in Preparation/Capturing/Analysis with unconfirmed data.
429 rate_limit_exceeded Rate limit exceeded Per-client request quota exceeded. See Retry-After.
500 catalog_not_configured Catalog not configured No job_family_version is marked as is_api_export. Contact Fontes support.
500 internal_error Internal error An unexpected error occurred. The traceId can be used by Fontes support to diagnose.

Example responses

customer_not_found (404)

{
  "type": "https://api.fontes.ee/problems/customer_not_found",
  "title": "Customer not found",
  "status": 404,
  "detail": "No customer with registration number '99999999' is linked to this API client.",
  "traceId": "00-abc123..."
}

The customerRegNo in your request body does not exist in the Fontes system, or it belongs to a different API client. Verify the registration number and that the customer has been set up by Fontes support.

validation_failed (422)

{
  "type": "https://api.fontes.ee/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "traceId": "00-def456...",
  "errors": [
    {
      "code": "validation_failed",
      "field": "rows[0].jobFamilyCode",
      "message": "Job family code 'JF999' is not in the catalog."
    },
    {
      "code": "validation_failed",
      "field": "rows[1].grossSalary",
      "message": "Gross salary must be greater than zero."
    }
  ]
}

Multiple validation errors are returned in a single response — do not fix one and submit again only to discover the next. Fix all reported errors before resubmitting, and generate a new Idempotency-Key when you do.

Logging guidance