미들웨어가 Cloud Healthcare API와 상호작용할 때 클라이언트와 미들웨어에 재시도 로직 및 제한 시간을 구현합니다. 클라이언트에서 재시도 한도를 초과하여 오류가 발생하면 클라이언트, 미들웨어 또는 기본 Cloud Healthcare API 서비스에서 오류가 발생했는지 여부를 식별할 수 있어야 합니다. 이는 특히 최종 오류 상태를 계획할 때 중요합니다.
다음 상황을 살펴보세요.
요청을 전송할 때 미들웨어가 Cloud Healthcare API에서 500 Internal Server Error 오류를 수신합니다.
미들웨어 레이어는 요청을 5회 더 재시도하고 한도에 도달하면 재시도를 중지합니다.
클라이언트에 최종 500 Internal Server Error 오류가 수신됩니다.
미들웨어가 아닌 Cloud Healthcare API에서 오류가 발생했음을 이해하는 것이 중요합니다. 디버깅을 간소화하려면 클라이언트에 반환된 오류에 이 정보를 제공합니다.
다음 다이어그램에서는 요청을 클라이언트에서 Cloud Healthcare API로 전달할 때 미들웨어 프록시가 500 Internal Server Error 오류를 수신하는 시나리오를 보여줍니다. 클라이언트와 프록시 모두 오류 처리 및 재시도를 구현합니다.
그림 1. 재시도 로직 및 제한 시간을 구현하는 데 필요한 레이어는 클라이언트 및 프록시입니다.
그림 1은 다음 단계를 보여줍니다.
클라이언트가 미들웨어 프록시를 통해 Cloud Healthcare API에 유효한 요청을 보냅니다.
프록시가 요청을 Cloud Healthcare API로 전달합니다.
Cloud Healthcare API가 500 Internal Server Error 오류를 프록시에 반환합니다. 프록시는 재시도 한도에 도달할 때까지 요청을 5회 더 재시도합니다.
프록시는 클라이언트에 최종 오류 상태 500 Internal Server Error를 반환합니다.
앞에서 설명한 권장사항을 사용하면 프록시가 클라이언트에 다음 오류를 반환하도록 하여 최종 오류 상태를 디버깅할 수 있습니다.
Error with underlying FHIR store in Cloud Healthcare API after 5 retries: 500 Internal Server Error
Cloud Healthcare API에서 반환된 오류에 대한 정보를 더 추가합니다.
경우에 따라 클라이언트나 프록시가 재시도 한도를 초과하여 500 Internal Server Error 오류를 수신하며 재시도할 수 없습니다. 이러한 경우에는 개발자가 개입해서 오류가 프록시나 Cloud Healthcare API에서 시작되었는지 진단해야 할 수 있습니다.
재시도할 오류 선택
시스템 아키텍처에 따라 특정 오류를 재시도하고 다른 오류는 무시할 수 있습니다. 다음은 재시도 가능한 Cloud Healthcare API 오류 코드의 일부 목록입니다.
408 Request Timeout
425 Too Early
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
이러한 오류는 일반적으로 동일한 빈도로 발생하지 않으며 일부는 발생하지 않을 수 있습니다.
시스템 아키텍처 효과
시스템 아키텍처는 오류 재시도 방법과 시기에 영향을 줍니다.
예를 들어 직접 클라이언트-서버 아키텍처에서 Cloud Healthcare API로부터 401 UNAUTHENTICATED 오류를 수신하는 클라이언트는 요청을 다시 인증하고 재시도할 수 있습니다.
시스템에 클라이언트와 Cloud Healthcare API 사이에 미들웨어 레이어가 있다고 가정해 보겠습니다. 클라이언트가 올바르게 인증되었고 만료된 인증 토큰으로 인해 문제가 발생한 경우 미들웨어는 토큰을 새로고침하고 요청을 재시도해야 합니다.
최종 오류 상태를 분석한 후 발견 항목에 따라 클라이언트에서 재시도하는 오류를 조정할 수 있습니다.
최종 오류 상태 계획
재시도 로직과 제한 시간을 구현한 후에도 클라이언트나 미들웨어는 재시도가 소진될 때까지 오류를 수신할 수 있습니다.
재시도와 제한 시간이 소진되기 전에 반환되는 마지막 오류가 최종 오류 상태입니다. 데이터 일관성 오류의 최종 오류 상태가 발생할 수 있습니다.
최종 오류 상태에 사람이 개입해야 하는 경우가 있습니다. 요청의 최종 오류 상태를 확인할 수 있는 방법을 구현해보세요.
그렇지 않으면 사람이 검토할 수 있도록 최종 오류 상태를 로깅합니다.
최종 오류 상태를 처리하는 방법을 계획할 때 다음 사항을 고려합니다.
FHIR 트랜잭션이나 번들을 성공적으로 완료할 수 없을 때 중지해야 하는 처리 종속 항목이 있나요?
여러 가상 머신(VM) 인스턴스가 영구적으로 실패하기 시작하면 클라이언트에서 실패한 요청을 보고해야 합니다. 문제가 해결되면 클라이언트에서 요청을 재시도해야 합니다.
Cloud Healthcare API는 확장 가능하고 성능이 뛰어난 서비스이지만 다음과 같은 이유로 인해 요청 지연 시간이 달라질 수 있습니다.
중요하지 않은 것으로 보이는 요청 간 사소한 차이로 인해 처리 시간이 추가될 수 있습니다.
비슷한 요청에서 지연 시간이 다를 수 있습니다.
예를 들어 데이터 스토리지에 레코드를 추가하는 두 가지 비슷한 요청에서 한 요청이 추가 스토리지 할당과 같은 추가 태스크를 트리거하는 임곗값을 초과할 경우 이러한 요청의 지연 시간이 다를 수 있습니다.
Cloud Healthcare API는 많은 요청을 동시에 처리합니다. 1초 미만의 시간으로 측정되는 클라이언트가 요청을 전송하는 시간이 Cloud Healthcare API가 평소보다 많은 로드로 작동하는 시간과 일치할 수 있습니다.
디스크와 같은 Cloud Healthcare API 물리적 리소스에서 여러 요청을 처리하는 경우 다른 요청을 처리하기 전에 큐에 추가된 태스크를 완료해야 합니다.
경우에 따라 Cloud Healthcare API가 서버 측에서 오류를 재시도하여 클라이언트 지연 시간이 증가할 수 있습니다.
리전 또는 멀티 리전 위치에 있는 여러 데이터 센터에 여러 데이터 사본이 있을 수 있습니다. 요청이 원래 요청 또는 재시도에 따라 여러 데이터 센터를 통해 라우팅될 경우 지연 시간이 증가할 수 있습니다.
백분위수 지연 시간 사용 계획
요청의 백분위수 지연 시간을 분석하여 지연 시간 증가를 계획할 수 있습니다. 다음 예시에서는 50번째 백분위수 지연 시간 및 99번째 백분위수 지연 시간에 대해 설명합니다.
50번째 백분위수 지연 시간은 요청의 가장 빠른 50%에 대한 최대 지연 시간(초)입니다. 예를 들어 50번째 백분위수 지연 시간이 0.5초라면 Cloud Healthcare API가 0.5초 내에 요청의 50%를 처리한 것입니다. 50번째 백분위수 지연 시간을 '지연 시간 중앙값'이라고도 부릅니다.
99번째 백분위수 지연 시간은 요청의 가장 빠른 99%에 대한 최대 지연 시간(초)입니다. 예를 들어 99번째 백분위수 지연 시간이 2초인 경우 Cloud Healthcare API가 2초 내에 요청의 99%를 처리한 것입니다.
Cloud Healthcare API가 소수의 요청만 처리할 때 간격에 대한 백분위수 지연 시간을 분석하는 경우 이상점 요청이 큰 영향을 받을 수 있으므로 백분위수 지연 시간이 유용하지 않거나 전체 성능을 나타내지 못을 수 있습니다.
예를 들어 Cloud Healthcare API의 한 프로세스에서 100분 동안 요청 100개를 처리한다고 가정해 보겠습니다. 100분 동안의 99번째 백분위수 지연 시간은 가장 느린 단일 요청을 기반으로 합니다. 단일 요청을 사용하는 지연 시간 측정은 성능 문제가 있는지 이해하는 데 부족합니다.
더 긴 기간(예: 24시간) 동안 더 큰 요청 샘플을 수집하면 시스템의 전체 동작에 대한 유용한 정보를 얻을 수 있습니다. 이러한 샘플을 사용하여 시스템이 과도한 트래픽에 대응하는 방법을 결정할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-18(UTC)"],[[["\u003cp\u003eImplement retry logic and timeouts in both the client and middleware to handle delays and errors caused by failed requests to the Cloud Healthcare API.\u003c/p\u003e\n"],["\u003cp\u003eIdentify the origin of errors—whether they occurred in the client, middleware, or the Cloud Healthcare API—to simplify debugging, especially when planning for final error states.\u003c/p\u003e\n"],["\u003cp\u003eCertain error codes, such as \u003ccode\u003e408 Request Timeout\u003c/code\u003e and \u003ccode\u003e500 Internal Server Error\u003c/code\u003e, are retryable, while others are not, so choose which errors to retry based on your system's architecture and error analysis.\u003c/p\u003e\n"],["\u003cp\u003ePlan for final error states, which occur when retries are exhausted, and consider whether human intervention or logging is necessary to resolve or review these states.\u003c/p\u003e\n"],["\u003cp\u003eAnalyze percentile latency, such as the 50th and 99th percentiles, over extended periods and with large request samples to understand how the system performs under varying loads and to account for potential latency variations.\u003c/p\u003e\n"]]],[],null,["# Request latency and error handling best practices\n\nThis page describes best practices for optimizing request latency and\nhandling errors in the Cloud Healthcare API. Implement\nthese practices as you plan and design your system architecture.\n\nGoogle provides a service-level agreement (SLA) that defines the\nexpected uptime of the Cloud Healthcare API service and how clients can handle errors.\nFor more information, see\n[Cloud Healthcare Service Level Agreement (SLA)](/healthcare/sla).\n\nImplement retry logic and timeouts\n----------------------------------\n\nTo handle delays and errors caused by failed requests, implement\nappropriate retry logic and timeouts. When setting the timeout duration, allow\nsufficient time to do the following:\n\n- Let the Cloud Healthcare API process the request.\n- Determine if the error originated from the service or the client.\n\nYou can retry some errors, but others are non-retryable and persist across\nmultiple retries. For example, if the request data is incorrectly formatted,\nthe server responds with a `400 Bad Request` status code. The request won't\nsucceed until you fix the data.\n\nTo handle these situations, you need to [plan for final error states](#plan-for).\n\nFor more information on retry logic and timeouts, see\n[Retry failed requests](/healthcare-api/docs/best-practices-data-throughput#retry-failed).\n\nHandle errors at multiple layers\n--------------------------------\n\nWhen middleware interacts with the Cloud Healthcare API, implement retry logic\nand timeouts in the client and middleware. If a client encounters\nerrors past its retry limit, you must be\nable to identify if the error occurred in the client, the middleware, or the\nunderlying Cloud Healthcare API service. This is especially important when\nplanning for final error states.\n\nConsider the following scenario:\n\n1. The middleware receives a `500 Internal Server Error` error from the Cloud Healthcare API when sending a request.\n2. The middleware layer retries the request five more times, reaching its limit, and then stops retrying.\n3. The client receives a final `500 Internal Server Error` error.\n\nIt's important to understand that the error\noriginated in the Cloud Healthcare API, not the middleware. To\nsimplify debugging, provide this information in the error returned to the\nclient.\n\nThe following diagram shows a scenario where a middleware proxy receives\n`500 Internal Server Error` errors when forwarding a request from a client to\nthe Cloud Healthcare API. The client and proxy both implement\nerror handling and retries.\n**Figure 1.** The layers where you need to implement retry logic and timeouts are the **Client** and the **Proxy**. \nFigure 1 shows the following steps:\n\n1. The client sends a valid request to the Cloud Healthcare API through a middleware proxy.\n2. The proxy forwards the request to the Cloud Healthcare API.\n3. The Cloud Healthcare API returns a `500 Internal Server Error` error to the proxy. The proxy retries the request five more times until its retry limit is reached.\n4.\n The proxy returns the final error state, `500 Internal Server Error`, to the client.\n\n\n Using the recommendations shown earlier, you can\n debug the final error state by having the proxy return the following\n error to the client: \n\n ```none\n Error with underlying FHIR store in Cloud Healthcare API after 5 retries: 500 Internal Server Error\n ```\n\n\n Add any more information about the error returned from the Cloud Healthcare API.\n\nSometimes, the client or proxy receives `500 Internal Server Error` errors\npast their retry limits and can't retry again. In this case, a human\nmight need to intervene to diagnose if the error came from the proxy or the\nCloud Healthcare API.\n\nChoose which errors to retry\n----------------------------\n\nDepending on your [system's architecture](#system-architecture), you can retry certain\nerrors and ignore others. The following is a non-exhaustive list of retryable Cloud Healthcare API\nerror codes:\n\n- `408 Request Timeout`\n- `425 Too Early`\n- `429 Too Many Requests`\n- `500 Internal Server Error`\n- `502 Bad Gateway`\n- `503 Service Unavailable`\n- `504 Gateway Timeout`\n\nThese errors typically don't occur at the same frequency, and some might never occur.\n\n### System architecture effects\n\nYour system's architecture influences how and when you retry errors.\n\nFor example, in a direct client-to-server architecture, a client that receives\na `401 UNAUTHENTICATED` error from the\nCloud Healthcare API can re-authenticate and retry its request.\n\nSuppose a system has a middleware layer\nbetween the client and the Cloud Healthcare API. If the client authenticated\ncorrectly and an expired [authentication token](/docs/authentication/token-types)\ncaused the issue, then\nthe middleware must [refresh the token](/docs/authentication/token-types#refresh)\nand retry the request.\n\nAfter analyzing final error states, you can adjust the errors your client\nretries based on your findings.\n\nPlan for final error states\n---------------------------\n\nEven after implementing retry logic and timeouts,\na client or middleware might receive errors until their retries are exhausted.\nThe last error returned before retries and\ntimeouts are exhausted is the *final error state*. You might encounter a final error\nstate for data consistency errors.\n\nSometimes, a final error state requires human intervention. Try to implement a\nsolution to resolve the final error state for a request.\nOtherwise, log the final error state so a human can review it.\n\nConsider the following when planning how to handle final error states:\n\n- Whether there are processing dependencies that need to stop if a FHIR transaction or bundle can't complete successfully.\n- If many virtual machine (VM) instances start failing permanently, a client must report the requests that failed. After the problem is fixed, the client must retry the requests.\n- Monitoring, alerting systems, and [service-level objectives (SLOs)](/stackdriver/docs/solutions/slo-monitoring/ui/create-slo) are necessary for ensuring the stability of your system. See [Test and monitor](/healthcare-api/docs/best-practices-data-throughput#test-and) for more information.\n\nPlan for increased latency\n--------------------------\n\nThe Cloud Healthcare API is a scalable and performant service, but request\nlatency can still vary for the following reasons:\n\n- Small differences between requests, even if they seem insignificant, can cause extra processing time.\n- Similar requests might have different latencies. For example, two similar requests that add a record to data storage might have different latencies if one crosses a threshold that triggers an extra task, like allocating more storage.\n- The Cloud Healthcare API handles many requests concurrently. The time when a client sends a request, measured in fractions of a second, might coincide with a time when the Cloud Healthcare API is under heavier load than usual.\n- If a Cloud Healthcare API physical resource, such as a disk, is handling many requests, it needs to complete its queued tasks before handling other requests.\n- Sometimes, the Cloud Healthcare API retries errors on the server-side, which can increase latency for clients.\n- There might be multiple copies of data in different data centers in a regional or multi-regional location. If your requests are routed across multiple data centers, either on the original request or on a retry, there might be increased latency.\n\n### Plan using percentile latency\n\nYou can plan for increased latency by analyzing the *percentile latency* of\nyour requests. The\nfollowing examples describe the *50th percentile latency* and the\n*99th percentile latency*:\n\n- The 50th percentile latency is the maximum latency, in seconds, for the fastest 50% of requests. For example, if the 50th percentile latency is 0.5 seconds, then the Cloud Healthcare API processed 50% of requests within 0.5 seconds. The 50th percentile latency is also called the \"median latency\".\n- The 99th percentile latency is the maximum latency, in seconds, for the fastest 99% of requests. For example, if the 99th percentile latency is two seconds, then the Cloud Healthcare API processed 99% of requests within two seconds.\n\nIf you analyze the percentile latency over an interval when the Cloud Healthcare API only\nprocessed a few requests, the percentile latency might not be useful or indicative\nof overall performance because outlier requests can have a large influence.\n\nFor example, suppose a process in the Cloud Healthcare API processes\n100 requests in 100 minutes. The 99th percentile latency for the 100 minutes would\nbe based on the single slowest request. A latency measurement using a single\nrequest isn't sufficient for understanding if there are performance\nissues.\n\nGathering a larger request sample over a longer time period, like 24 hours,\ncan provide more insight into the overall\nbehavior of your system. You can use these samples to determine how your system\nresponds to heavy traffic."]]
