Errors

Valydar uses standard HTTP status codes and consistent error responses.

Error Response Format

{
  "error": { "code": "unauthorized", "message": "Invalid API key" }
}

HTTP Status Codes

Status	Meaning
200	Success
201	Created
400	Bad Request — invalid input
401	Unauthorized — missing or invalid API key
402	Payment Required — plan limit / monthly quota reached
403	Forbidden — key doesn't have permission
404	Not Found — resource doesn't exist
409	Conflict — resource already exists
413	Payload Too Large — file exceeds 10MB
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Common Errors

Invalid API Key

{
  "error": { "code": "unauthorized", "message": "Invalid API key" }
}

Fix: Check your API key is correct and includes a valid API key.

Rate Limited

{
  "error": { "code": "rate_limited", "message": "Rate limit exceeded" }
}

Requests-per-minute depend on your plan. Responses include Retry-After (seconds) and X-RateLimit-Limit.

Fix: Implement exponential backoff and respect Retry-After.

Payment Required (plan limit)

Returned when your plan doesn't include a feature, or your monthly verification quota is reached.

{
  "error": {
    "code": "payment_required",
    "message": "monthly verification limit reached for the free plan (100/100); upgrade to continue"
  }
}

Fix: Upgrade your plan (e.g. via checkout) or wait for the next billing cycle.

Verification Not Found

{
  "error": { "code": "not_found", "message": "Verification not found" }
}

Fix: Check the verification ID is correct.

File Too Large

{
  "error": { "code": "payload_too_large", "message": "File exceeds maximum size of 10MB" }
}

Fix: Compress the image before uploading.

Missing Document

{
  "error": { "code": "bad_request", "message": "Document required before running face match" }
}

Fix: Upload a document before running face match.