Breeder API — error codes reference

Error response format

All errors use the same JSON envelope. The `code` field is machine-readable for programmatic handling.

{
  "error": "Human-readable description",
  "code": "MACHINE_READABLE_CODE",
  "details": [...] // optional, present on validation errors
}

Authentication errors (401)

Returned when the request cannot be authenticated.

• `INVALID_API_KEY` — API key not found, revoked, or belongs to a deleted account
• `API_KEY_EXPIRED` — API key has passed its expiry date. Generate a new key.
• `Unauthorised` — No API key or session cookie provided

Authorization errors (403)

Returned when the request is authenticated but the caller lacks permission.

• `TIER_INSUFFICIENT` — Your subscription tier does not include this feature. The response includes an `upgradeUrl` field.

Validation errors (400)

Returned when request data fails schema validation. The `details` array contains one entry per failed field.

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    { "path": ["price"], "message": "Price cannot exceed $50,000" }
  ]
}

Resource errors (404)

Returned when a resource is not found or does not belong to your account.

• Listing, pairing, saved search, or API key not found
• Resource exists but belongs to a different user

Conflict errors (409)

Returned when a create operation would cause a duplicate.

• `DUPLICATE_NAME` — A saved search or API key with this name already exists
• `DUPLICATE_ENTRY` — User is already on this waitlist

Business logic errors (422)

Returned when the request is valid but violates a business rule.

• `KEY_LIMIT_REACHED` — You have 10 active API keys. Revoke one before creating another.
• `WAITLIST_DISABLED` — Waitlist is not enabled for this pairing
• Image limit exceeded for your subscription tier

Rate limit errors (429)

Returned when you exceed 1,000 requests per hour. Check the `X-RateLimit-Remaining` response header to track usage. The `X-RateLimit-Reset` header contains the Unix timestamp when your limit resets.

curl -I https://herpify.com/api/breeder/listings \
  -H "Authorization: Bearer hm_live_your_key_here"
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 847
# X-RateLimit-Reset: 1746647400