Diagnostics & Reliability

API Errors & Resilience Guide

The CVFormatter API communicates errors through standard HTTP/1.1 response status codes paired with machine-readable JSON payloads. Every error response includes a unique request trace ID to accelerate troubleshooting and vendor support.

Structured error response schema

Every 4xx and 5xx response body adheres to a consistent JSON envelope containing a standardized error code and debugging metadata:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "No resume credits available in active organization.",
    "request_id": "req_88f9102b",
    "details": {
      "credits_available": 0,
      "credits_required": 1,
      "account_type": "subscription"
    }
  }
}

code

Machine-readable string identifier (e.g., INSUFFICIENT_CREDITS) suitable for client-side programmatic branching.

message

Human-readable description explaining why the request failed and what validation rule triggered the rejection.

request_id

Unique identifier logged across our microservices. Provide this ID when contacting CVFormatter customer support.

HTTP status codes & diagnostic reference

Comprehensive reference of all HTTP status codes returned by CVFormatter public gateway endpoints:

Status Code	What Happened	Remediation Action
400 Bad Request	Malformed request syntax, invalid JSON body, or missing required parameter.	Check parameter names and schema. Ensure file sizes remain below the 20MB limit.
401 Unauthorized	Missing or invalid API token string.	Verify that your key begins with `cvf_live_` and is supplied via the `Authorization: Bearer <key>` header.
402 Payment Required	Zero resume or auto-proofread credits remaining across all pools.	Purchase PAYG top-ups or upgrade your monthly subscription plan in the dashboard.
403 Forbidden	Key lacks permission scopes, or an individual recruiter key attempted an admin-only route.	Switch to an Organization Key or add missing OAuth permission scopes (e.g. `resumes:export`).
409 Conflict	Idempotency conflict or resume not yet completed.	If querying data, verify status is `COMPLETED`. If uploading, generate a fresh unique UUID for the Idempotency-Key.
415 Unsupported Media	The uploaded binary format is not supported by our document extractor.	Convert file to supported formats: PDF, DOCX, DOC, PNG, or JPEG.
429 Too Many Requests	Rate limits exceeded for your plan tier.	Pause requests and inspect the `Retry-After` header for required wait duration in seconds.
500 / 503 Server Error	Temporary backend fault, model timeout, or database reconnection.	Retry with exponential backoff using the identical Idempotency-Key to avoid double billing.

Recommended retry & exponential backoff algorithm

For production enterprise integrations handling high-volume ATS workflows, use truncated exponential backoff with full jitter to handle transient network interruptions and HTTP 5xx responses:

Delay Formula: t = min(max_delay, base_delay * 2^attempt) ± random_jitter

Retryable Statuses: Only retry on HTTP 429, 500, 502, 503, 504, or TCP socket timeouts.
Non-Retryable Statuses: Never automatically retry 400, 401, 402, or 415 without modifying the payload, as these reflect deterministic client errors.
Idempotency Preservation: Always transmit the original Idempotency-Key header during retries. If the server processed your document before the network dropped, you will safely receive the original result with zero duplicate billing.

Escalation & developer support

If an unexpected HTTP 500 error persists, capture the request_id from the JSON error body or response headers (X-Request-Id). Our engineering team can look up the complete trace across our distributed parser cluster.