Hippomundo Enterprise

Compatibility policy · Changelog

Searches horses by name, parentage and registration identifiers. Returns thin disambiguation results; the Hippomundo id is the only horse identifier returned. Each result names its sire and dam without their IDs; a pedigree returns the parents' IDs. FEI numbers and UELNs are accepted as filters but never returned.

Name filters match names that start with the text you send, ignoring case: NORTHW finds NORTHWIND VAN HET ELSHOF, but ELSHOF does not. Each name filter needs at least two characters after surrounding spaces are removed; a shorter value returns 422 validation_failed with out_of_range and is not charged.

Identifier matching is never fuzzy or phonetic: fei and ueln match the complete identifier exactly; there is no partial match. Both accept letters and digits, ignore case, and ignore spaces, hyphens and other ASCII punctuation, so an identifier copied from a passport or another system works as written. Other characters, such as accented letters or typographic dashes, are rejected.

Supplied sire_id/dam_id values are transparently resolved to canonical identifiers before matching.

Unknown query parameters are rejected with 422 validation_failed. The page size is capped and defaulted at 25; a smaller page_size is allowed and becomes bound to the traversal token, after which page_size and sort overrides are rejected. When sort is omitted, ordering is relevance when a text filter is present and id otherwise. Use id for exhaustive traversal.

Each successful page, including an empty page (data: [], total: 0), is charged at this operation's current price, which your OpenAPI document (GET /v1/openapi.json) and your portal API reference show. Errors are never charged.

Parameters

Field	Type	Description
`name`	query · string	Horse name to search, covering current and birth name. Matches names that start with this text, ignoring case: `NORTHW` finds `NORTHWIND VAN HET ELSHOF`, but `ELSHOF` does not. At least two characters after trimming. Minimum length: `2`.
`sire_name`	query · string	Sire name to search. Matches sire names that start with this text, ignoring case, like `name`. At least two characters after trimming. Minimum length: `2`.
`dam_name`	query · string	Dam name to search. Matches dam names that start with this text, ignoring case, like `name`. At least two characters after trimming. Minimum length: `2`.
`sire_id`	query · integer (int64)	Exact public sire (father) horse ID.
`dam_id`	query · integer (int64)	Exact public dam (mother) horse ID.
`fei`	query · string	FEI number to match exactly; the number is not returned in results. Letters and digits only; case, spaces, hyphens and other ASCII punctuation are ignored, so `104-xy55` matches `104XY55`. Any other character, such as an accented letter or a typographic dash, returns `422 validation_failed` with `invalid_format`. A value that more than 1,000 horses share, such as a placeholder, identifies no horse and returns `422 validation_failed` with `unsupported_value`.
`ueln`	query · string	UELN to match exactly; the UELN is not returned in results. Letters and digits only; case, spaces, hyphens and other ASCII punctuation are ignored, so `056 015 Z55123456` matches `056015Z55123456`. Any other character, such as an accented letter or a typographic dash, returns `422 validation_failed` with `invalid_format`. A value that more than 1,000 horses share identifies no horse and returns `422 validation_failed` with `unsupported_value`.
`sort`	query · string	Sort profile. Defaults to `relevance` when a text filter is present, otherwise `id`. Every profile is a deterministic total order ending in `id`. `id` is recommended for exhaustive traversal. Rejected as an override once a traversal has begun. Allowed values: `["relevance","name","id"]`.
`page_size`	query · integer	Page size, capped at 25. Bound to the traversal token; rejected as an override once a traversal has begun. Default: `25`. Minimum: `1`. Maximum: `25`.
`page_token`	query · string	Opaque signed continuation token from `next_page_token` of the previous page. It is bound to the originating query parameters, sort profile, page size and API key, and expires. Callers never interpret its contents. Once a traversal has begun, per-request `sort` or `page_size` overrides are rejected. A malformed, signature-invalid or mismatched token returns `400 invalid_page_token`; an expired token returns `400 page_token_expired` and the traversal restarts from page one.
`X-Hippomundo-Freshness`	header · string	Requests fresher data for this call. `live` bypasses the freshness cache; the override may only request fresher data and never affects price. Any other value fails validation. Allowed values: `["cached","live"]`.
`Hippomundo-Version`	header · string	Optional pin to the API version your integration was built against. The only accepted value is `v1`, which today changes nothing. If a later version of the API changes behaviour in a way that is not backwards compatible, requests that send `v1` keep the v1 behaviour. Any other value returns `400 unsupported_version`.
`Idempotency-Key`	header · string	Optional idempotency key for billable requests. Reuse by the same API key with the same normalized request within 24 hours never creates a second debit. A repeat within that window of a successful request that was charged or used a free allowance is not charged again: it answers with `Idempotent-Replayed: true` and `Hippomundo-Charged-Milli-Credits: 0`. Its response is read again, so it may carry current data and a new `next_page_token`. A success that cost nothing for another reason is not recorded under the key, so a repeat of it is priced like a new request and carries no `Idempotent-Replayed`. A free page stays free. A free repeat of a request you paid for shortly before is charged once that free period has passed. A repeat of an uncharged failure runs again. Reuse with a different normalized request within 24 hours of a success that was charged or used a free allowance returns an uncharged `409 idempotency_conflict`. A key with no such success, or whose 24 hours have passed, takes a different request as a new one. Without the header, each request is independent. Maximum length: `255`.

Response 200 · application/json

One page of horse search results.

Field	Type	Description
`Body`	HorseSearchPage
`Header: Cache-Control`	string · required	Always `private, no-store` on successful responses: data can change at any time, so no cache may store or reuse them, and the API answers no conditional requests.
`Header: Hippomundo-Charged-Milli-Credits`	integer (int64) · required	The milli-credits this request debited from your balance, read from the recorded charge; one credit is 1,000 milli-credits. `0` when the request debited nothing, for example on a free operation, under a free allowance, or on an idempotent replay. Error responses are never charged and do not carry this header. Minimum: `0`.
`Header: Hippomundo-Data-Generation`	string	Sandbox only. Names the copy of the sandbox data that answered this request. The weekly data refresh replaces that copy and publishes a new value, so a client that keeps sandbox data can key it on this value. HTTP caches still may not store the response (`Cache-Control: private, no-store`). A `next_page_token` issued under an earlier value answers `400 page_token_expired`. Absent in production, and in the sandbox until its first refresh. Pattern: `"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"`.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: Idempotent-Replayed`	string	`true` when this response answers a repeat, within 24 hours and with the same `Idempotency-Key`, of an earlier successful request that was charged or used a free allowance. The repeat is not charged again, so `Hippomundo-Charged-Milli-Credits` is `0`. Absent otherwise, including on a repeat of a request that cost nothing for another reason. Allowed values: `["true"]`.
`Header: X-RateLimit-Limit`	integer	Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses.
`Header: X-RateLimit-Remaining`	integer	Requests remaining in the applied rate-limit window.

Related schemas: HorseSearchPage

Example

{
  "data": [
    {
      "birth_country_iso_code": "BE",
      "birth_year": 2013,
      "dam_name": "WENDELINA",
      "id": 104233,
      "name": "NORTHWIND VAN HET ELSHOF",
      "sex": "mare",
      "sire_name": "EXAMPLE CORNET",
      "studbook": {
        "abbreviation": "BWP",
        "id": 4
      }
    },
    {
      "birth_country_iso_code": null,
      "birth_year": null,
      "dam_name": null,
      "id": 118450,
      "name": "NORTHWIND B",
      "sex": null,
      "sire_name": null,
      "studbook": null
    }
  ],
  "has_more": false,
  "next_page_token": null,
  "total": 2
}

Response 400 · application/problem+json

400 — one of the registered codes malformed_request, invalid_page_token, page_token_expired or unsupported_version; branch on the body code. Not retryable without changing the request. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Page token is malformed or mismatched

{
  "charged": false,
  "code": "invalid_page_token",
  "detail": "The supplied page token is not valid for this query and API key.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000001",
  "request_id": "01J5AR8Q2K0000000000000001",
  "retryable": false,
  "status": 400,
  "title": "Invalid page token",
  "type": "https://enterprise.hippomundo.com/docs/errors/invalid_page_token"
}

Request syntax cannot be parsed

{
  "charged": false,
  "code": "malformed_request",
  "detail": "The request could not be parsed.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000000",
  "request_id": "01J5AR8Q2K0000000000000000",
  "retryable": false,
  "status": 400,
  "title": "Malformed request",
  "type": "https://enterprise.hippomundo.com/docs/errors/malformed_request"
}

Page token past its public expiry

{
  "charged": false,
  "code": "page_token_expired",
  "detail": "The traversal token has expired; restart from page one.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000002",
  "request_id": "01J5AR8Q2K0000000000000002",
  "retryable": false,
  "status": 400,
  "title": "Page token expired",
  "type": "https://enterprise.hippomundo.com/docs/errors/page_token_expired"
}

Hippomundo-Version is not supported

{
  "charged": false,
  "code": "unsupported_version",
  "detail": "The requested API version is not supported.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000003",
  "request_id": "01J5AR8Q2K0000000000000003",
  "retryable": false,
  "status": 400,
  "title": "Unsupported version",
  "type": "https://enterprise.hippomundo.com/docs/errors/unsupported_version"
}

Response 401 · application/problem+json

401 invalid_api_key — the API key is missing, invalid, revoked or otherwise unusable; the states are deliberately indistinguishable. Not retryable without different credentials. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: WWW-Authenticate`	string · required	Always `ApiKey`, without credential detail.

Related schemas: Problem

API key missing, invalid, revoked or otherwise unusable

{
  "charged": false,
  "code": "invalid_api_key",
  "detail": "The request was not authenticated.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000004",
  "request_id": "01J5AR8Q2K0000000000000004",
  "retryable": false,
  "status": 401,
  "title": "Invalid API key",
  "type": "https://enterprise.hippomundo.com/docs/errors/invalid_api_key"
}

Response 402 · application/problem+json

402 — one of the registered codes insufficient_credits, account_in_arrears or api_key_credit_cap_reached; branch on the body code because the remediation differs. Top up after insufficient_credits and settle the negative balance after account_in_arrears; neither is retryable until remediated. api_key_credit_cap_reached means the request would take this API key past the credit cap its owner set for each UTC day or UTC calendar month. A request that costs less may still succeed. It is retryable: Retry-After gives the seconds until the next period starts and the full cap is available again, and the owner can also raise or remove the cap in the portal. The body never states balances, caps or pricing internals; the portal and usage API are the authenticated source for financial detail. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: Retry-After`	integer	Seconds to wait before retrying. Required on `429` and on `402 api_key_credit_cap_reached`, where it counts to the start of the next UTC day or month; present on `503` when the service knows a meaningful recovery interval. Minimum: `0`.

Related schemas: Problem

Negative balance blocks metered calls

{
  "charged": false,
  "code": "account_in_arrears",
  "detail": "A negative balance blocks metered calls until it is settled.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000006",
  "request_id": "01J5AR8Q2K0000000000000006",
  "retryable": false,
  "status": 402,
  "title": "Account in arrears",
  "type": "https://enterprise.hippomundo.com/docs/errors/account_in_arrears"
}

The request would take the API key past its credit cap for the current period

{
  "charged": false,
  "code": "api_key_credit_cap_reached",
  "detail": "This request would take the API key past the credit cap its owner set for the current period. A request that costs less may still succeed, and the full cap is available again when the next period starts.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000M",
  "request_id": "01J5AR8Q2K000000000000000M",
  "retryable": true,
  "status": 402,
  "title": "API key credit cap reached",
  "type": "https://enterprise.hippomundo.com/docs/errors/api_key_credit_cap_reached"
}

Spendable credits cannot cover the maximum authorized cost

{
  "charged": false,
  "code": "insufficient_credits",
  "detail": "The account does not hold enough spendable credits for this request.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000005",
  "request_id": "01J5AR8Q2K0000000000000005",
  "retryable": false,
  "status": 402,
  "title": "Insufficient credits",
  "type": "https://enterprise.hippomundo.com/docs/errors/insufficient_credits"
}

Response 403 · application/problem+json

403 endpoint_not_entitled — the authenticated Customer lacks a required entitlement for a discoverable public endpoint it has not purchased. Private endpoints never return 403; they return 404 not_found. Not retryable without purchasing the entitlement. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Public endpoint not purchased

{
  "charged": false,
  "code": "endpoint_not_entitled",
  "detail": "The account is not entitled to this endpoint.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K0000000000000007",
  "request_id": "01J5AR8Q2K0000000000000007",
  "retryable": false,
  "status": 403,
  "title": "Endpoint not entitled",
  "type": "https://enterprise.hippomundo.com/docs/errors/endpoint_not_entitled"
}

Response 406 · application/problem+json

406 not_acceptable — the Accept header excludes application/json, the media type of every successful response. Omit the header or send one that admits application/json, for example application/json, application/* or */*. Error responses are always application/problem+json. Not retryable without changing the Accept header. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Requested response media type unsupported

{
  "charged": false,
  "code": "not_acceptable",
  "detail": "The requested response media type is not supported.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000A",
  "request_id": "01J5AR8Q2K000000000000000A",
  "retryable": false,
  "status": 406,
  "title": "Not acceptable",
  "type": "https://enterprise.hippomundo.com/docs/errors/not_acceptable"
}

Response 409 · application/problem+json

409 idempotency_conflict — the same Customer or key reused an idempotency key for a different normalized request within 24 hours of a success under that key that was charged or used a free allowance. Not retryable with the same key; use a new idempotency key for a new request. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Idempotency key reused for a different request

{
  "charged": false,
  "code": "idempotency_conflict",
  "detail": "This idempotency key was already used for a different request.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000B",
  "request_id": "01J5AR8Q2K000000000000000B",
  "retryable": false,
  "status": 409,
  "title": "Idempotency conflict",
  "type": "https://enterprise.hippomundo.com/docs/errors/idempotency_conflict"
}

Response 422 · application/problem+json

422 validation_failed — parsed public inputs fail the documented schema or combination rules. errors lists up to 20 field-level items in request-field order, without messages or rejected values; errors_truncated may be true when more exist. Not retryable without correcting the request. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Parsed public inputs fail the documented rules

{
  "charged": false,
  "code": "validation_failed",
  "detail": "One or more request parameters are invalid.",
  "errors": [
    {
      "code": "invalid_format",
      "field": "date_from",
      "location": "query"
    }
  ],
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000E",
  "request_id": "01J5AR8Q2K000000000000000E",
  "retryable": false,
  "status": 422,
  "title": "Request validation failed",
  "type": "https://enterprise.hippomundo.com/docs/errors/validation_failed"
}

Response 429 · application/problem+json

429 rate_limit_exceeded — the Customer or key rate policy rejected the request. Retryable after waiting at least Retry-After; preserve the same idempotency key for a billable retry. Carries the same rate-limit headers used on successful authenticated responses. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: Retry-After`	integer	Seconds to wait before retrying. Required on `429` and on `402 api_key_credit_cap_reached`, where it counts to the start of the next UTC day or month; present on `503` when the service knows a meaningful recovery interval. Minimum: `0`.
`Header: X-RateLimit-Limit`	integer	Request quota of the applied rate-limit window. The same rate-limit headers appear on successful authenticated responses.
`Header: X-RateLimit-Remaining`	integer	Requests remaining in the applied rate-limit window.

Related schemas: Problem

Rate policy rejected the request

{
  "charged": false,
  "code": "rate_limit_exceeded",
  "detail": "The rate limit for this API key was exceeded.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000F",
  "request_id": "01J5AR8Q2K000000000000000F",
  "retryable": true,
  "status": 429,
  "title": "Rate limit exceeded",
  "type": "https://enterprise.hippomundo.com/docs/errors/rate_limit_exceeded"
}

Response 500 · application/problem+json

500 internal_error — an unexpected Hippomundo failure with no safer public classification. Retryability is occurrence-specific; honor the body retryable field, use exponential backoff with jitter, preserve the idempotency key and report persistent failures with the request_id. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

Unexpected failure with no safer classification

{
  "charged": false,
  "code": "internal_error",
  "detail": "An unexpected internal error occurred.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000G",
  "request_id": "01J5AR8Q2K000000000000000G",
  "retryable": false,
  "status": 500,
  "title": "Internal error",
  "type": "https://enterprise.hippomundo.com/docs/errors/internal_error"
}

Response 502 · application/problem+json

502 dependency_error — a required managed dependency returned an invalid or failing response. Retryability is occurrence-specific; honor the body retryable field. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

A managed dependency returned an invalid or failing response

{
  "charged": false,
  "code": "dependency_error",
  "detail": "A required internal dependency failed.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000H",
  "request_id": "01J5AR8Q2K000000000000000H",
  "retryable": false,
  "status": 502,
  "title": "Dependency error",
  "type": "https://enterprise.hippomundo.com/docs/errors/dependency_error"
}

Response 503 · application/problem+json

503 service_unavailable — the service or a required ledger or dependency is temporarily unavailable. Retryable; honor Retry-After when present and use exponential backoff with jitter. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.
`Header: Retry-After`	integer	Seconds to wait before retrying. Required on `429` and on `402 api_key_credit_cap_reached`, where it counts to the start of the next UTC day or month; present on `503` when the service knows a meaningful recovery interval. Minimum: `0`.

Related schemas: Problem

Service temporarily unavailable

{
  "charged": false,
  "code": "service_unavailable",
  "detail": "The service is temporarily unavailable.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000J",
  "request_id": "01J5AR8Q2K000000000000000J",
  "retryable": true,
  "status": 503,
  "title": "Service unavailable",
  "type": "https://enterprise.hippomundo.com/docs/errors/service_unavailable"
}

Response 504 · application/problem+json

504 dependency_timeout — a required dependency exceeded its deadline. Retryable with exponential backoff and jitter; preserve the idempotency key so a billable retry cannot double-charge. Uncharged.

Field	Type	Description
`Body`	Problem	RFC 9457 problem document used by every managed error response under `/v1`, regardless of which layer produced it. Content type is always `application/problem+json`. Clients branch on `code`, retain an unknown-code fallback, use `status` only for broad handling and must ignore unknown top-level fields. `title` and `detail` are human-readable English, may be clarified without versioning and are never parsed.
`Header: Cache-Control`	string · required	Always `no-store` on error responses.
`Header: Hippomundo-Request-ID`	string · required	Compact server-generated request identifier carried on every response. On errors it equals the body `request_id`. Quote it in support requests; it contains no customer identity. An inbound customer-supplied value is never trusted as this identifier.

Related schemas: Problem

A dependency exceeded its deadline

{
  "charged": false,
  "code": "dependency_timeout",
  "detail": "A required internal dependency timed out.",
  "instance": "urn:hippomundo:request:01J5AR8Q2K000000000000000K",
  "request_id": "01J5AR8Q2K000000000000000K",
  "retryable": true,
  "status": 504,
  "title": "Dependency timeout",
  "type": "https://enterprise.hippomundo.com/docs/errors/dependency_timeout"
}

OpenAPI definition

Related schemas: HorseSearchPage

Complete OpenAPI definition

{
  "description": "Searches horses by name, parentage and registration identifiers.\nReturns thin disambiguation results; the Hippomundo `id` is the only\nhorse identifier returned. Each result names its sire and dam without\ntheir IDs; a pedigree returns the parents' IDs. FEI numbers and UELNs\nare accepted as filters but never returned.\n\nName filters match names that start with the text you send, ignoring\ncase: `NORTHW` finds `NORTHWIND VAN HET ELSHOF`, but `ELSHOF` does\nnot. Each name filter needs at least two characters after surrounding\nspaces are removed; a shorter value returns `422 validation_failed`\nwith `out_of_range` and is not charged.\n\nIdentifier matching is never fuzzy or phonetic: `fei` and `ueln`\nmatch the complete identifier exactly; there is no partial match.\nBoth accept letters and digits, ignore case, and ignore spaces,\nhyphens and other ASCII punctuation, so an identifier copied from a\npassport or another system works as written. Other characters, such\nas accented letters or typographic dashes, are rejected.\n\nSupplied `sire_id`/`dam_id` values are transparently resolved to\ncanonical identifiers before matching.\n\nUnknown query parameters are rejected with `422 validation_failed`.\nThe page size is capped and defaulted at 25; a smaller `page_size`\nis allowed and becomes bound to the traversal token, after which\n`page_size` and `sort` overrides are rejected. When `sort` is\nomitted, ordering is `relevance` when a text filter is present and\n`id` otherwise. Use `id` for exhaustive traversal.\n\nEach successful page, including an empty page (`data: []`,\n`total: 0`), is charged at this operation's current price, which your\nOpenAPI document (`GET /v1/openapi.json`) and your portal API\nreference show. Errors are never\ncharged.\n",
  "operationId": "searchHorses",
  "parameters": [
    {
      "description": "Horse name to search, covering current and birth name. Matches names that start with this text, ignoring case: `NORTHW` finds `NORTHWIND VAN HET ELSHOF`, but `ELSHOF` does not. At least two characters after trimming.",
      "in": "query",
      "name": "name",
      "schema": {
        "minLength": 2,
        "type": "string"
      }
    },
    {
      "description": "Sire name to search. Matches sire names that start with this text, ignoring case, like `name`. At least two characters after trimming.",
      "in": "query",
      "name": "sire_name",
      "schema": {
        "minLength": 2,
        "type": "string"
      }
    },
    {
      "description": "Dam name to search. Matches dam names that start with this text, ignoring case, like `name`. At least two characters after trimming.",
      "in": "query",
      "name": "dam_name",
      "schema": {
        "minLength": 2,
        "type": "string"
      }
    },
    {
      "description": "Exact public sire (father) horse ID.",
      "in": "query",
      "name": "sire_id",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "Exact public dam (mother) horse ID.",
      "in": "query",
      "name": "dam_id",
      "schema": {
        "format": "int64",
        "type": "integer"
      }
    },
    {
      "description": "FEI number to match exactly; the number is not returned in results. Letters and digits only; case, spaces, hyphens and other ASCII punctuation are ignored, so `104-xy55` matches `104XY55`. Any other character, such as an accented letter or a typographic dash, returns `422 validation_failed` with `invalid_format`. A value that more than 1,000 horses share, such as a placeholder, identifies no horse and returns `422 validation_failed` with `unsupported_value`.",
      "in": "query",
      "name": "fei",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "UELN to match exactly; the UELN is not returned in results. Letters and digits only; case, spaces, hyphens and other ASCII punctuation are ignored, so `056 015 Z55123456` matches `056015Z55123456`. Any other character, such as an accented letter or a typographic dash, returns `422 validation_failed` with `invalid_format`. A value that more than 1,000 horses share identifies no horse and returns `422 validation_failed` with `unsupported_value`.",
      "in": "query",
      "name": "ueln",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Sort profile. Defaults to `relevance` when a text filter is present, otherwise `id`. Every profile is a deterministic total order ending in `id`. `id` is recommended for exhaustive traversal. Rejected as an override once a traversal has begun.",
      "in": "query",
      "name": "sort",
      "schema": {
        "enum": [
          "relevance",
          "name",
          "id"
        ],
        "type": "string"
      }
    },
    {
      "description": "Page size, capped at 25. Bound to the traversal token; rejected as an override once a traversal has begun.",
      "in": "query",
      "name": "page_size",
      "schema": {
        "default": 25,
        "maximum": 25,
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "$ref": "#/components/parameters/PageToken"
    },
    {
      "$ref": "#/components/parameters/FreshnessOverride"
    },
    {
      "$ref": "#/components/parameters/VersionHeader"
    },
    {
      "$ref": "#/components/parameters/IdempotencyKey"
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "example": {
            "data": [
              {
                "birth_country_iso_code": "BE",
                "birth_year": 2013,
                "dam_name": "WENDELINA",
                "id": 104233,
                "name": "NORTHWIND VAN HET ELSHOF",
                "sex": "mare",
                "sire_name": "EXAMPLE CORNET",
                "studbook": {
                  "abbreviation": "BWP",
                  "id": 4
                }
              },
              {
                "birth_country_iso_code": null,
                "birth_year": null,
                "dam_name": null,
                "id": 118450,
                "name": "NORTHWIND B",
                "sex": null,
                "sire_name": null,
                "studbook": null
              }
            ],
            "has_more": false,
            "next_page_token": null,
            "total": 2
          },
          "schema": {
            "$ref": "#/components/schemas/HorseSearchPage"
          }
        }
      },
      "description": "One page of horse search results.",
      "headers": {
        "Cache-Control": {
          "$ref": "#/components/headers/CacheControlPrivateNoStore"
        },
        "Hippomundo-Charged-Milli-Credits": {
          "$ref": "#/components/headers/HippomundoChargedMilliCredits"
        },
        "Hippomundo-Data-Generation": {
          "$ref": "#/components/headers/HippomundoDataGeneration"
        },
        "Hippomundo-Request-ID": {
          "$ref": "#/components/headers/HippomundoRequestId"
        },
        "Idempotent-Replayed": {
          "$ref": "#/components/headers/IdempotentReplayed"
        },
        "X-RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimitLimit"
        },
        "X-RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimitRemaining"
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/EndpointNotEntitled"
    },
    "406": {
      "$ref": "#/components/responses/NotAcceptable"
    },
    "409": {
      "$ref": "#/components/responses/IdempotencyConflict"
    },
    "422": {
      "$ref": "#/components/responses/ValidationFailed"
    },
    "429": {
      "$ref": "#/components/responses/RateLimitExceeded"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    },
    "502": {
      "$ref": "#/components/responses/DependencyError"
    },
    "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
    },
    "504": {
      "$ref": "#/components/responses/DependencyTimeout"
    }
  },
  "summary": "Search horses",
  "tags": [
    "search"
  ]
}