Skip to main content

CvDeepMatchError

Standard error envelope returned by every CV DeepMatch endpoint on a non-2xx response.

error objectrequired
codestringrequired

Stable machine-readable error code.

  • INVALID_INPUT — one or more fields failed validation; per-field detail in error.details.fields.
  • UNAUTHENTICATED — no API key was supplied or it could not be resolved to a client. Returned with HTTP 401 on the read paths (poll / list).
  • MISSING_PERMISSION — no API key, invalid API key, or the client's permissions[] does not contain cvdeepmatch.
  • INVALID_FILE_CONTENT — the uploaded cv_file passed the MIME/extension gate but its bytes did not start with a valid PDF magic header.
  • INSECURE_WEBHOOK_URL — webhook_url is http://. HTTPS is required.
  • PRIVATE_WEBHOOK_URL — webhook_url resolves to a private, loopback, or link-local IP address.
  • INSUFFICIENT_CREDITS — client balance is below the per-match minimum. error.details includes required and balance.
  • STEP_FUNCTIONS_FAILED — the downstream matching pipeline failed to start. Retry-safe.
  • REQUEST_NOT_FOUND — no request with that id exists for this client. Also returned cross-tenant to avoid leaking the existence of other clients' IDs.
  • INTERNAL_ERROR — uncategorised server error.
  • RATE_LIMITED — too-fast polling (POST rate-limit has its own dedicated handler in the platform). Honour the Retry-After header.

Possible values: [INVALID_INPUT, UNAUTHENTICATED, MISSING_PERMISSION, INVALID_FILE_CONTENT, INSECURE_WEBHOOK_URL, PRIVATE_WEBHOOK_URL, INSUFFICIENT_CREDITS, STEP_FUNCTIONS_FAILED, REQUEST_NOT_FOUND, INTERNAL_ERROR, RATE_LIMITED]

messagestringrequired

Human-readable message; safe to surface to staff but not always to end users.

requestIdstringnullable

Correlation ID for this error response (not the CV DeepMatch id).

timestampdate-timerequired
details object

Code-specific structured detail. For INVALID_INPUT this contains { "fields": { "<field>": ["<message>", …] } }; for INSUFFICIENT_CREDITS it contains { "required": <n>, "balance": <n> }; for RATE_LIMITED it contains { "retry_after_seconds": <n> }. May be {}.

property name*any

Code-specific structured detail. For INVALID_INPUT this contains { "fields": { "<field>": ["<message>", …] } }; for INSUFFICIENT_CREDITS it contains { "required": <n>, "balance": <n> }; for RATE_LIMITED it contains { "retry_after_seconds": <n> }. May be {}.

CvDeepMatchError
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "string",
    "requestId": "string",
    "timestamp": "2024-07-29T15:51:28.071Z",
    "details": {}
  }
}