Errors

Every Partner API error is an RFC 7807 problem document with content type application/problem+json. The HTTP status tells you the class of failure; the platformResponseCode tells you the exact cause and is stable across releases, so branch on it rather than on title or detail text.

The envelope

{
  "type": "https://api.unitedpetclub.com/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "App-level rate limit exceeded. Retry after 12 seconds.",
  "instance": "/api/animal/v1/animals",
  "correlationId": "0HN4…",
  "platformResponseCode": "0010010000429",
  "scope": "app",
  "limit": 600,
  "retryAfterSeconds": 12
}

Field	Always present	Meaning
`type`	yes	A URI identifying the error kind. The last segment is a stable slug.
`title`	yes	Short human-readable summary.
`status`	yes	Mirrors the HTTP status.
`detail`	yes	Human-readable explanation for this occurrence. Not stable — do not parse it.
`instance`	yes	The request path.
`correlationId`	yes	Unique id for this request. Include it in any support ticket.
`platformResponseCode`	yes	13-digit stable cause code. Branch on this.
`errors`	on validation failures	Array of `{ "field", "message" }` naming the invalid inputs.
(extensions)	varies	Some errors add fields — `429` adds `scope`, `limit` and `retryAfterSeconds`.

Response codes

Status	`type` slug	`platformResponseCode`	Cause	What to do
`400`	varies	varies	Invalid input — bad `page`/`pageSize`, malformed body, missing required parameter. `errors[]` names the fields when applicable.	Fix the request. Do not retry unchanged.
`400`	`validation-failed`	`0010010000400`	A Partner API or business-resource request failed the edge’s own checks (a missing date range, a `limit` out of range, a missing `client`; `page` or `pageSize` out of range; a platform-invoice page deeper than 1,000; a message without `clientId` or `body`). `detail` says what.	Fix the request. Do not retry unchanged.
`401`	—	`0010010000401`	Missing, malformed, wrong-audience or expired token. The `WWW-Authenticate` header points at the discovery metadata.	Request a new token and retry once.
`401`	`token-revoked` / `authorization-revoked`	`0010010000402`	The token, your application’s access to the account (a business disconnected your app), or the application itself was revoked.	Stop retrying; a new token will also be rejected until access is restored.
`403`	—	`0010010000403`	Your application lacks the operation’s scope.	Request the scope through Support.
`403`	—	`0010010000404`	The account has not granted your application the operation’s permission.	The account owner must adjust the role they gave your application.
`403`	`delegated-token-required`	`0010010000406`	A client-credentials token on a Partner API route, which acts for a business.	Use the token from the business’s authorization-code grant — see Connecting a business.
`403`	`payment-card-required`	`0010010000407`	The business the token acts for has no valid payment card on file (none added, or it expired, was declined or needs re-verification). The Partner API is free, but a business must keep a card on file before an app can act for it.	Tell the business; it adds a card in its Dashboard (Finances → Billing). Do not retry automatically; calls work again within about 10 seconds of the card being added.
`404`	`not-found`, or no body	the service’s code, when there is a body	No resource with that id is visible to your application. On a business route, a resource of another business answers exactly like one that does not exist.	Treat as not found.
`409`	`conflict`	the service’s code	A write lost to the state of the business’s data — the slot is gone, an `Idempotency-Key` was reused with another body, a limit was reached; an animal that duplicates one the business has; a message to a guest client who has no United Pet Club inbox.	See the code; for a slot, search again and offer another time.
`429`	`rate-limited`	the service’s code	A daily cap of the service, relayed: messages to clients reach at most 50 clients per business and 5 messages per client in 24 hours. No `Retry-After`.	Do not retry in a loop; send later.
`429`	`rate-limit-exceeded`	`0010010000429`	Rate limit exceeded. `scope` is `app` or `install`; `retryAfterSeconds` and the `Retry-After` header say how long to wait.	Wait `Retry-After` seconds, then retry with backoff. See Rate limits.
`500`	`internal-error`	`0010010000500`	Unexpected failure.	Retry with backoff; report the `correlationId` if it persists.
`502`	`bc-unavailable`	`0010010000502`	The service behind this resource could not be reached.	Retry with backoff. Persistent `502` on a resource family usually means it is not yet enabled — see the API reference.
`503`	`service-degraded`	`0010010000503`	The service behind this resource is temporarily shedding load — or, on the Partner API, the business’s connection or payment card could not be checked (`Retry-After: 5`).	Retry with backoff after at least a few seconds.
`504`	`bc-timeout`	`0010010000504`	The service behind this resource did not answer in time.	Retry with backoff. Reads are safe to retry; for writes, re-read first to see whether the change applied.

Codes beginning 0010010000 are raised by the API edge itself. Other 13-digit codes are passed through from the underlying service unchanged and are documented with the resource that emits them. On the Partner API (/api/scheduling/v1), a refusal of the booking or client service keeps its status (400, 403, 404, 409, 503) and its platformResponseCode is the service’s governed code name — for example Scheduling_SchedulingPartner_AD_Slot_RJ — listed in the booking guide. The business resources relay the same way, and also relay a 429; each resource’s page lists its codes, for example Animal_AnimalRegistry_GT_Resource_FL.

Handling errors well

Branch on platformResponseCode, then on status. title and detail are for humans and may be reworded.
Retry only what the table says is retryable — 429 (but not a relayed daily cap), 500, 502, 503, 504 — with exponential backoff and jitter, honouring Retry-After when present.
Never retry 401 0010010000402 or any 403 automatically; they need a human or a configuration change — for a connected business, the business itself.
Log correlationId with every non-2xx response. It is the only thing that lets Support find your request.
Responses are JSON even on failure; a non-JSON body means the request never reached the API (proxy, DNS, TLS) and should be treated as a transport error.