Errors

Handle common Vardera API error responses.

Vardera API errors use standard HTTP status codes. Every error body has a detail string describing the failure.

StatusMeaning
400The request is invalid and needs correction.
401The bearer token is missing or invalid.
403The assessment endpoint or requested operations are not enabled.
413A photo is over 15 MB, or the request is over 20 MB.
415POST /images received a body that is neither multipart nor JSON.
429The service is busy. Retry after Retry-After.
500The API encountered an unexpected error.
503The assessment models are unavailable. Retry after Retry-After.

A 400 response includes a human-readable detail describing what needs to be corrected. For example:

{
  "detail": "Invalid `include[0]`: Input should be 'identity' or 'valuation'."
}

No assessment is created when the API returns 400.

A 403 response means the category endpoint is not enabled for your organization, or include lists a section your organization does not have enabled. For example:

{
  "detail": "This organization does not have access to card assessments."
}
{
  "detail": "Requested operations are not enabled for this organization: grade."
}

No assessment is created when the API returns 403. Cards, coins and banknotes refuse the request if any listed section is not enabled. Toys refuse it only when none is; otherwise the assessment runs with the enabled sections and issues reports the ones left out. Sealed packs are enabled by card identity: without it, the request is refused with This organization does not have access to sealed pack assessments.

Retries

Retry 429 and 5xx responses with exponential backoff and jitter. Honor Retry-After when it is provided, and use a limited number of attempts.

Do not retry a 400 or 413 unchanged; use detail to correct the request. For a 401, provide a valid bearer token before trying again. Do not retry a 403 unchanged; contact Vardera if your integration requires access to that endpoint or operation.

Assessment submissions are not idempotent. Retrying a request may create another assessment; external_id does not prevent duplicates.

Concurrency and capacity

Your organization has a guaranteed number of concurrent assessments per category (cards, sealed packs, coins, banknotes, toys). Requests within that number are always accepted. Above it, requests are still accepted while the service has spare capacity, so there is no fixed ceiling on your concurrency.

When you are above your guarantee and the service is busy, the API returns 429 Too Many Requests with a Retry-After header. Retrying a 429 is always safe: no result was produced. Keeping your client's concurrency at or below your guarantee avoids almost all 429s.

In the rare case that the card, sealed pack, coin or banknote models as a whole are full, the API also returns 429 with a Retry-After header, whatever your guarantee. If the models are unavailable, it returns 503 Service Unavailable with a Retry-After header. Retry either one after the interval. Neither produced a result, and retrying sends a new assessment.

There is no limit on the total number of requests per day or month. Contact us to confirm your guarantee, or before intentionally sending high-volume traffic or running a load test so we can coordinate capacity.