{"openapi":"3.1.0","info":{"title":"ASINtoJSON API","version":"1.0.0","description":"Retrieve normalized public Amazon product metadata from an ASIN or Amazon product URL. ASINtoJSON is independent and is not affiliated with Amazon."},"servers":[{"url":"https://asintojson.com"}],"security":[],"paths":{"/api/v1/lookup":{"post":{"operationId":"lookupProductMetadata","summary":"Look up one Amazon product","description":"Current production policy: 5 lookup requests per minute per server-derived client identity and 20 fresh lookups per UTC day per identity. Cache hits count against the minute request limit but do not consume fresh/day quota. Negative cache results do not consume fresh/day quota. Fresh failures do not consume finalized daily quota. Concurrent lookups for the same product may share acquisition; followers do not consume another fresh quota. Only a fresh successful acquisition consumes fresh quota. Daily quota resets at the next UTC day boundary. remaining=null means quota status is temporarily unavailable, not unlimited usage. Protective fallback limits may be stricter during a storage outage. Maximum JSON request body: 16 KiB / 16,384 bytes, enforced before JSON parsing. No API key is currently required. Intended for server-to-server clients, AI agents, scripts, and curl; arbitrary third-party browser frontends are not supported through wildcard CORS. Do not automatically retry when retryable=false. When retryable=true, a caller may wait and retry. Prefer the HTTP Retry-After header when provided; otherwise use retry_after_seconds when present. If neither is present, use bounded backoff. Do not retry every 5xx response: HTTP 500 and 502 are non-retryable.","x-max-request-body-bytes":16384,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupRequest"},"examples":{"asin":{"summary":"Bare ASIN with an explicit marketplace","value":{"input":"B01LR5RG08","marketplace":"amazon.com"}},"url":{"summary":"A URL keeps its own marketplace","value":{"input":"https://www.amazon.co.uk/dp/B0C27P6VC9","request_id":"example-request-123"}}}}},"description":"Content-Type application/json or application/json; charset=utf-8. Maximum body: 16,384 bytes (16 KiB)."},"responses":{"200":{"description":"Normalized product metadata. Nullable fields and empty arrays indicate unavailable source values. The example is illustrative, not a promise about any live product.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupSuccess"},"example":{"ok":true,"data":{"asin":"B01LR5RG08","marketplace":"amazon.com","source_url":"https://www.amazon.com/dp/B01LR5RG08","currency":"USD","canonical_url":"https://www.amazon.com/dp/B01LR5RG08","title":"Illustrative product title","main_image":null,"images":[],"rating":null,"review_count":null,"category":[],"brand":null,"bsr":null,"product_information":[{"title":"Product details","attributes":{"ASIN":"B01LR5RG08"}}]},"meta":{"request_id":"example-request-123","cached":false,"fetched_at":"2026-10-14T12:00:00.000Z","quota":{"limit":20,"remaining":19,"reset":"2026-10-15T00:00:00.000Z"}},"warnings":["MAIN_IMAGE_MISSING","RATING_MISSING","REVIEW_COUNT_MISSING","CATEGORY_MISSING"]}}}},"400":{"description":"INVALID_INPUT: Missing, malformed, invalid, or unsupported request input. retryable=false. UNSUPPORTED_MARKETPLACE: The requested Amazon marketplace is not supported. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"INVALID_INPUT"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UNSUPPORTED_MARKETPLACE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}}]},"examples":{"INVALID_INPUT":{"value":{"ok":false,"error":{"code":"INVALID_INPUT","message":"Missing, malformed, invalid, or unsupported request input.","retryable":false},"meta":{"request_id":"example-request-123"}}},"UNSUPPORTED_MARKETPLACE":{"value":{"ok":false,"error":{"code":"UNSUPPORTED_MARKETPLACE","message":"The requested Amazon marketplace is not supported.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"404":{"description":"PRODUCT_NOT_FOUND: No active product was found in the selected marketplace. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PRODUCT_NOT_FOUND"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"PRODUCT_NOT_FOUND":{"value":{"ok":false,"error":{"code":"PRODUCT_NOT_FOUND","message":"No active product was found in the selected marketplace.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"409":{"description":"PRODUCT_UNAVAILABLE: The product is currently unavailable. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PRODUCT_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"PRODUCT_UNAVAILABLE":{"value":{"ok":false,"error":{"code":"PRODUCT_UNAVAILABLE","message":"The product is currently unavailable.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"410":{"description":"PRODUCT_RETIRED: The product is no longer available. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PRODUCT_RETIRED"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"PRODUCT_RETIRED":{"value":{"ok":false,"error":{"code":"PRODUCT_RETIRED","message":"The product is no longer available.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"413":{"description":"PAYLOAD_TOO_LARGE: The request body exceeds 16,384 bytes. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PAYLOAD_TOO_LARGE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"PAYLOAD_TOO_LARGE":{"value":{"ok":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"The request body exceeds 16,384 bytes.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"415":{"description":"INVALID_INPUT: Content-Type must be application/json; charset=utf-8 is also accepted. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"INVALID_INPUT"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"INVALID_INPUT":{"value":{"ok":false,"error":{"code":"INVALID_INPUT","message":"Content-Type must be application/json; charset=utf-8 is also accepted.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"429":{"description":"RATE_LIMITED: The per-identity minute request limit has been reached. retryable=true. DAILY_QUOTA_EXCEEDED: The daily fresh lookup quota has been reached; wait until UTC reset. retryable=true.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}},"Retry-After":{"description":"Optional positive delay in seconds. When present, prefer this header before retrying.","schema":{"type":"string","pattern":"^[1-9][0-9]*$"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"RATE_LIMITED"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"DAILY_QUOTA_EXCEEDED"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}}]},"examples":{"RATE_LIMITED":{"value":{"ok":false,"error":{"code":"RATE_LIMITED","message":"The per-identity minute request limit has been reached.","retryable":true,"retry_after_seconds":30},"meta":{"request_id":"example-request-123"}}},"DAILY_QUOTA_EXCEEDED":{"value":{"ok":false,"error":{"code":"DAILY_QUOTA_EXCEEDED","message":"The daily fresh lookup quota has been reached; wait until UTC reset.","retryable":true,"retry_after_seconds":30},"meta":{"request_id":"example-request-123"}}}}}}},"500":{"description":"INTERNAL_ERROR: The lookup could not be completed safely. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"INTERNAL_ERROR":{"value":{"ok":false,"error":{"code":"INTERNAL_ERROR","message":"The lookup could not be completed safely.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"502":{"description":"UPSTREAM_UNAVAILABLE: Amazon returned a response that could not be processed. retryable=false.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UPSTREAM_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"UPSTREAM_UNAVAILABLE":{"value":{"ok":false,"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Amazon returned a response that could not be processed.","retryable":false},"meta":{"request_id":"example-request-123"}}}}}}},"503":{"description":"SERVICE_BUSY: The lookup service is temporarily busy. retryable=true. UPSTREAM_UNAVAILABLE: Amazon is temporarily unavailable for lookup. retryable=true.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}},"Retry-After":{"description":"Optional positive delay in seconds. When present, prefer this header before retrying.","schema":{"type":"string","pattern":"^[1-9][0-9]*$"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"SERVICE_BUSY"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UPSTREAM_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}}]},"examples":{"SERVICE_BUSY":{"value":{"ok":false,"error":{"code":"SERVICE_BUSY","message":"The lookup service is temporarily busy.","retryable":true,"retry_after_seconds":30},"meta":{"request_id":"example-request-123"}}},"UPSTREAM_UNAVAILABLE":{"value":{"ok":false,"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Amazon is temporarily unavailable for lookup.","retryable":true,"retry_after_seconds":30},"meta":{"request_id":"example-request-123"}}}}}}},"504":{"description":"UPSTREAM_UNAVAILABLE: Amazon took too long to respond. retryable=true.","headers":{"Cache-Control":{"description":"Always no-store for public JSON responses.","schema":{"type":"string","const":"no-store"}},"Retry-After":{"description":"Optional positive delay in seconds. When present, prefer this header before retrying.","schema":{"type":"string","pattern":"^[1-9][0-9]*$"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UPSTREAM_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},"examples":{"UPSTREAM_UNAVAILABLE":{"value":{"ok":false,"error":{"code":"UPSTREAM_UNAVAILABLE","message":"Amazon took too long to respond.","retryable":true,"retry_after_seconds":30},"meta":{"request_id":"example-request-123"}}}}}}}}}}},"components":{"schemas":{"LookupRequest":{"type":"object","additionalProperties":false,"required":["input"],"properties":{"input":{"type":"string","description":"Amazon ASIN or supported Amazon product URL. The runtime accepts at most 4,096 UTF-16 code units for input. ASCII characters each use one code unit; supplementary Unicode characters may use two. The full request body is separately limited to 16,384 bytes. Standard JSON Schema maxLength does not express this runtime code-unit limit. ASINs are ten alphanumeric characters, normalized to uppercase after trimming. Supported URL paths: /dp/{ASIN}, /gp/product/{ASIN}, /gp/aw/d/{ASIN}. The URL's recognized marketplace takes precedence over marketplace. Short links, search pages, and unlisted hostnames are not supported."},"marketplace":{"type":"string","description":"Optional marketplace for a bare ASIN, at most 64 UTF-16 code units at runtime; defaults to amazon.com when omitted or empty. Canonical supported hostnames: amazon.com, amazon.ca, amazon.com.mx, amazon.com.br, amazon.co.uk, amazon.de, amazon.fr, amazon.it, amazon.es, amazon.nl, amazon.se, amazon.pl, amazon.co.jp, amazon.in, amazon.com.au, amazon.sg, amazon.ae, amazon.sa. Hostname matching is case-insensitive and accepts a www. prefix and a trailing dot. Unsupported non-empty values return UNSUPPORTED_MARKETPLACE, even when input is a product URL.","x-supported-marketplaces":["amazon.com","amazon.ca","amazon.com.mx","amazon.com.br","amazon.co.uk","amazon.de","amazon.fr","amazon.it","amazon.es","amazon.nl","amazon.se","amazon.pl","amazon.co.jp","amazon.in","amazon.com.au","amazon.sg","amazon.ae","amazon.sa"]},"request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$","description":"Optional caller correlation identifier: 8–128 ASCII letters, digits, underscores, or hyphens. This is not an idempotency key. A server identifier is generated if omitted or the body cannot be safely parsed."}}},"ProductMetadata":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asin":{"type":"string"},"marketplace":{"type":"string"},"source_url":{"type":"string"},"currency":{"type":"string"},"canonical_url":{"type":"string"},"title":{"type":"string"},"main_image":{"anyOf":[{"type":"string"},{"type":"null"}]},"images":{"type":"array","items":{"type":"string"}},"rating":{"anyOf":[{"type":"number"},{"type":"null"}]},"review_count":{"anyOf":[{"type":"number"},{"type":"null"}]},"category":{"type":"array","items":{"type":"string"}},"brand":{"anyOf":[{"type":"string"},{"type":"null"}]},"bsr":{"anyOf":[{"type":"number"},{"type":"null"}]},"product_information":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["title","attributes"],"additionalProperties":false}}},"required":["asin","marketplace","source_url","currency","canonical_url","title","main_image","images","rating","review_count","category","brand","bsr","product_information"],"additionalProperties":false},"Warnings":{"type":"array","items":{"type":"string","enum":["MAIN_IMAGE_MISSING","RATING_MISSING","REVIEW_COUNT_MISSING","CATEGORY_MISSING"]},"maxItems":4,"uniqueItems":true,"description":"Required array of allowlisted warnings, at most four unique codes. May be empty."},"Quota":{"type":"object","additionalProperties":false,"required":["limit","remaining","reset"],"properties":{"limit":{"type":"number"},"remaining":{"type":["number","null"],"description":"Remaining fresh quota. null means status is temporarily unavailable, not unlimited."},"reset":{"type":"string","description":"Next UTC day boundary in ISO form, e.g. 2026-10-15T00:00:00.000Z."}}},"LookupSuccess":{"type":"object","additionalProperties":false,"required":["ok","data","meta","warnings"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/ProductMetadata"},"meta":{"type":"object","additionalProperties":false,"required":["request_id","cached","fetched_at","quota"],"properties":{"request_id":{"type":"string"},"cached":{"type":"boolean"},"fetched_at":{"type":"string","description":"Original acquisition timestamp, not cache delivery time, in ISO form."},"quota":{"$ref":"#/components/schemas/Quota"}}},"warnings":{"$ref":"#/components/schemas/Warnings"}}},"FailureMeta":{"type":"object","additionalProperties":false,"required":["request_id"],"properties":{"request_id":{"type":"string","description":"Caller request_id when safely accepted, otherwise a server-generated identifier."}}},"PublicLookupFailure":{"oneOf":[{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"INVALID_INPUT"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UNSUPPORTED_MARKETPLACE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PRODUCT_NOT_FOUND"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PRODUCT_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PRODUCT_RETIRED"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"PAYLOAD_TOO_LARGE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"RATE_LIMITED"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"DAILY_QUOTA_EXCEEDED"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UPSTREAM_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":false}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"SERVICE_BUSY"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}},{"type":"object","additionalProperties":false,"required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","const":"UPSTREAM_UNAVAILABLE"},"message":{"type":"string"},"retryable":{"type":"boolean","const":true},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Optional positive delay in seconds; only emitted for retryable failures when a valid delay is available."}}},"meta":{"$ref":"#/components/schemas/FailureMeta"}}}],"description":"Do not automatically retry when retryable=false. When retryable=true, a caller may wait and retry. Prefer the HTTP Retry-After header when provided; otherwise use retry_after_seconds when present. If neither is present, use bounded backoff. Do not retry every 5xx response: HTTP 500 and 502 are non-retryable."}}}}