Petnow LogoPetnow

Why Did Registration Fail?

Every place a registration, verification, or identification can fail, where you see the failure reason, and what to do next.

A failure shows up in one of three places, depending on when it happens. Find your case first.

Where you saw itWhat it meansReason available?Go to
An HTTP 4xx/5xx with errors[].code (PETNOWB2B…) when you call the APIThe request was refused before any job startedYes, in the code1. Request refused
A job with status: FAILED (polling, or a *.failed webhook)The job started and could not produce a resultNo reason field2. Job FAILED
petify_status=failed on your redirect, or a hosted session with status: FAILEDA Web Integration session failedYes on the session (errorCode); limited on the redirect3. Web Integration session failed

Not a failure: a verification that does not match (isVerified: false) or an identification with no match (isMatch: false everywhere) is a successful job. The result was produced; the pet simply did not match.

1. Request refused (HTTP error code)

The response body carries the reason:

{ "errors": [{ "code": "PETNOWB2B20015" }] }

Common registration-time codes:

CodeHTTPCauseWhat to do
PETNOWB2B10000401API key invalid or deactivatedCheck the key in the Console
PETNOWB2B10005402Payment required (pet limit / no payment method)Register a payment method in the Console
PETNOWB2B20007400The pet already has a registration job runningWait for that job to finish
PETNOWB2B20012400The capture session is not finishedFinish uploading before you submit
PETNOWB2B20014400The capture session was already usedCreate a new capture session
PETNOWB2B20015400Species does not matchUse the pet's species
PETNOWB2B20018409The capture session is older than 24 hoursCreate a new capture session
PETNOWB2B21001409Web Integration: externalPetId already registeredUse another ID, or delete the existing pet
PETNOWB2B21003400Web Integration: redirectUrl not on the allow-listAdd the URL in the Console first

The full list with every code is on Error Codes.

2. Job FAILED (Server API)

Registration (addFingerprints), verification, and identification run as asynchronous jobs. A FAILED job response contains only status. There is no error code or reason field, in polling responses and in *.failed webhook events alike.

A job fails asynchronously when the images cannot produce a result, most often because of insufficient image quality:

  • the nose is blurred, too dark, or covered by glare;
  • the images show a photo or a screen instead of a live animal (rejected by the fake-image check);
  • the images are not of the pet's nose.

What to do

  1. Start a new capture session and capture again with the SDK's on-screen guidance. See Capture guidance.
  2. Submit the job again with the new session.
  3. A failed registration can leave a pet profile without fingerprints (hasFingerprint: false). It still counts for billing, so delete it or retry on the same pet. See Cleaning up incomplete records.

If the same pet keeps failing with good images, contact support@petnow.io with the jobId.

3. Web Integration session failed

On the redirect your return page gets petify_status=failed. petify_code is present only for one reason, FEATURE_UNAVAILABLE (identification not available on the account's plan). Other failures, such as capture quality, carry no code. See Completion redirect parameters.

On your server, read the session with GET /v2/hosted-sessions/{id} (reference). A failed session has status: FAILED and an errorCode:

errorCodeMeaningWhat to do
CAPTURE_FAILEDCapture or quality check could not produce a resultOffer the user a new link or session
DUPLICATE_EXTERNAL_PET_IDThe externalPetId is already registeredUse another ID, or delete the existing pet in the Console
IDENTIFICATION_NOT_IN_PLANIdentification is not in the planChoose Plus under My Page → Billing
IDENTIFICATION_PLAN_SELECTION_REQUIREDNo plan selected yetSelect a plan under My Page → Billing

errorCode is an open list: handle unknown values as a generic failure. Web Integration sessions send no webhook events (Getting Results).

On this page