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 it | What it means | Reason available? | Go to |
|---|---|---|---|
An HTTP 4xx/5xx with errors[].code (PETNOWB2B…) when you call the API | The request was refused before any job started | Yes, in the code | 1. Request refused |
A job with status: FAILED (polling, or a *.failed webhook) | The job started and could not produce a result | No reason field | 2. Job FAILED |
petify_status=failed on your redirect, or a hosted session with status: FAILED | A Web Integration session failed | Yes on the session (errorCode); limited on the redirect | 3. 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:
| Code | HTTP | Cause | What to do |
|---|---|---|---|
PETNOWB2B10000 | 401 | API key invalid or deactivated | Check the key in the Console |
PETNOWB2B10005 | 402 | Payment required (pet limit / no payment method) | Register a payment method in the Console |
PETNOWB2B20007 | 400 | The pet already has a registration job running | Wait for that job to finish |
PETNOWB2B20012 | 400 | The capture session is not finished | Finish uploading before you submit |
PETNOWB2B20014 | 400 | The capture session was already used | Create a new capture session |
PETNOWB2B20015 | 400 | Species does not match | Use the pet's species |
PETNOWB2B20018 | 409 | The capture session is older than 24 hours | Create a new capture session |
PETNOWB2B21001 | 409 | Web Integration: externalPetId already registered | Use another ID, or delete the existing pet |
PETNOWB2B21003 | 400 | Web Integration: redirectUrl not on the allow-list | Add 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
- Start a new capture session and capture again with the SDK's on-screen guidance. See Capture guidance.
- Submit the job again with the new session.
- 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:
errorCode | Meaning | What to do |
|---|---|---|
CAPTURE_FAILED | Capture or quality check could not produce a result | Offer the user a new link or session |
DUPLICATE_EXTERNAL_PET_ID | The externalPetId is already registered | Use another ID, or delete the existing pet in the Console |
IDENTIFICATION_NOT_IN_PLAN | Identification is not in the plan | Choose Plus under My Page → Billing |
IDENTIFICATION_PLAN_SELECTION_REQUIRED | No plan selected yet | Select 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).
Related
- Getting Results: polling, webhooks, and redirects
- Error Codes: every
PETNOWB2Bcode - Troubleshooting