Skip to content

Error Handling

Ivan William Harsono edited this page Nov 17, 2026 · 2 revisions

Error handling

Bahasa / Language: English · Bahasa Indonesia


English

SATUSEHAT reports almost every rejection as HTTP 400, so the status code alone is not enough: the OperationOutcome body and the rule numbers carry the meaning.

Reading a response

resp = ss.post("Patient", patient_payload)

if not resp.is_success():
    print(resp.get_http_code())          # 400
    for message in resp.get_error_messages():
        print(message)

SSResponse exposes get_http_code(), get_body(), get_content(), is_success(), is_error(), get_error_messages() and get_resource_id(); the same values are also available as properties (http_code, body, content).

Classifying an error

from satusehat_integration.queue.error_classifier import ErrorClassifier

result = ErrorClassifier.classify(resp.get_http_code(), resp.get_body())

result["category"]    # "validation_error"
result["retryable"]   # False
result["status"]      # queue status to apply: success / pending / dlq
result["detail"]      # extracted from the FHIR issues, or a generic sentence
category HTTP Meaning Action
CAT_SUCCESS 2xx Accepted —
CAT_INVALID_REQUEST 400 Malformed request Fix the payload
CAT_UNAUTHORIZED 401 Token expired or wrong oauth2.refresh_token()
CAT_FORBIDDEN 403 Insufficient scope Check the client's scopes
CAT_NOT_FOUND 404 Resource not found Verify the IHS number
CAT_CONFLICT 409 / 412 Already exists, or changed Read it back, decide update vs skip
CAT_VALIDATION_ERROR 422 Field-level rejection Fix the field named in detail
CAT_RATE_LIMITED 429 Too many requests Wait, then retry
CAT_SERVER_ERROR 5xx Server-side failure Retry with backoff
CAT_NETWORK_ERROR timeout / 408 No answer Retry
CAT_UNEXPECTED other Unclassified Log the body, look at it

retryable already answers "should this go back into the queue" — use it instead of re-testing the status code, or the two lists drift apart.

Parsing the OperationOutcome yourself

for issue in resp.get_body().get("issue", []):
    print(issue.get("severity"), issue.get("code"), issue.get("details", {}).get("text"))

Rule numbers

from satusehat_integration import SSValidationError

error = SSValidationError.from_response(resp)
error.get_rule_numbers()      # [10101]
error.get_affected_paths()    # ["Patient.identifier[0].value"]
error.is_duplicate()
error.is_date_time_error()

Full catalogue: Validation-Rule-Numbers.

Retry policy that will not make things worse

  • Retry only when retryable is true.
  • Honour Retry-After on 429 instead of a fixed sleep.
  • A duplicate on 409 is a success for an idempotent sender — read the existing resource instead of posting again.

Bahasa Indonesia

SATUSEHAT melaporkan hampir semua penolakan sebagai HTTP 400, jadi kode status saja tidak cukup: isi OperationOutcome dan nomor aturan yang membawa maknanya.

Membaca respons

resp = ss.post("Patient", patient_payload)

if not resp.is_success():
    print(resp.get_http_code())          # 400
    for message in resp.get_error_messages():
        print(message)

SSResponse menyediakan get_http_code(), get_body(), get_content(), is_success(), is_error(), get_error_messages(), dan get_resource_id(); nilai yang sama juga tersedia sebagai properti (http_code, body, content).

Mengelompokkan galat

from satusehat_integration.queue.error_classifier import ErrorClassifier

result = ErrorClassifier.classify(resp.get_http_code(), resp.get_body())

result["category"]    # "validation_error"
result["retryable"]   # False
result["status"]      # status antrean: success / pending / dlq
result["detail"]      # diambil dari issue FHIR, atau kalimat umum
category HTTP Arti Tindakan
CAT_SUCCESS 2xx Diterima —
CAT_INVALID_REQUEST 400 Permintaan cacat Perbaiki payload
CAT_UNAUTHORIZED 401 Token kedaluwarsa/salah oauth2.refresh_token()
CAT_FORBIDDEN 403 Scope kurang Periksa scope klien
CAT_NOT_FOUND 404 Resource tidak ada Pastikan nomor IHS
CAT_CONFLICT 409 / 412 Sudah ada, atau berubah Baca ulang, tentukan update atau lewati
CAT_VALIDATION_ERROR 422 Ditolak per field Perbaiki field yang disebut di detail
CAT_RATE_LIMITED 429 Terlalu banyak permintaan Tunggu, lalu ulangi
CAT_SERVER_ERROR 5xx Gagal di sisi server Ulangi dengan backoff
CAT_NETWORK_ERROR timeout / 408 Tidak ada jawaban Ulangi
CAT_UNEXPECTED lain Belum terklasifikasi Catat body, periksa manual

retryable sudah menjawab "perlukah ini masuk antrean lagi" — pakai itu, jangan menguji ulang kode status, supaya dua daftar itu tidak berbeda sendiri.

Membaca OperationOutcome sendiri

for issue in resp.get_body().get("issue", []):
    print(issue.get("severity"), issue.get("code"), issue.get("details", {}).get("text"))

Nomor aturan

from satusehat_integration import SSValidationError

error = SSValidationError.from_response(resp)
error.get_rule_numbers()      # [10101]
error.get_affected_paths()    # ["Patient.identifier[0].value"]
error.is_duplicate()
error.is_date_time_error()

Katalog lengkap: Validation-Rule-Numbers.

Kebijakan ulang yang tidak memperburuk keadaan

  • Ulangi hanya bila retryable benar.
  • Hormati Retry-After pada 429, jangan tidur dengan durasi tetap.
  • Duplikat 409 adalah sukses bagi pengirim idempoten — baca resource yang sudah ada, jangan kirim ulang.

Clone this wiki locally