Error reference¶

Single-page consumer playbook για όλα τα errors του Estia.API. Συμπυκνώνει το error-handling.md (εις βάθος), το provider-error-matrix.md (per-provider table) και τις 23 σελίδες ανά provider σε ένα γρήγορο reference για production code.

TL;DR — 5 κανόνες¶

Το status code είναι το μόνο που χρειάζεσαι για retry decisions. provider, providerStatusCode, providerErrorMessage είναι μόνο για display/logging.
4xx → σταμάτα. Διόρθωσε request ή credentials.
5xx → retry. Exponential backoff με jitter (defaults: 1s initial, 2× multiplier, 5 attempts, ±25% jitter, 30s cap).
422 → εμφάνισε providerErrorMessage στον end-user. Είναι actionable business message.
502 / 504 → εμφάνισε generic message + traceId για support. ΜΗΝ εκθέτεις provider* extensions σε end-user (internal info).

Master status code table¶

Ένας consumer που χτυπάει οποιοδήποτε από τους 23 providers του Estia.API θα δει αυτά τα status codes — και μόνο αυτά.

Status	Τι σημαίνει	Retry;	Που έγινε;	Consumer action
200/201/204	Επιτυχία	—	—	Όπως πάντα
400	Bad Request / malformed input	❌ No	Estia API layer (πριν τον provider)	Διόρθωσε JSON, missing fields, types
401	Unauthorized	❌ Refresh token	Keycloak (Estia layer)	Πάρε νέο bearer token από `client_credentials`
403	Forbidden	❌ Permission issue	Keycloak (Estia layer)	Λείπει role/scope — επικοινώνησε με admin
404	Not Found	❌ No	Route ή resource	Έλεγξε URL ή resource ID
422	Provider business error	❌ No (fix request)	Upstream provider business rule	Δείξε `providerErrorMessage` στον end-user
429	Rate limit	✅ With `Retry-After`	Estia API layer	Εξειδίκευση: `Retry-After` header value
500	Internal server error	⚠️ Limited (~2 attempts)	Estia API bug	Στείλε `traceId` στο support
502	Upstream provider error	✅ Yes (exp backoff)	Upstream transport/SOAP fault/parse	Retry. Αν επιμένει, support
504	Upstream timeout	✅ Yes (μεγαλύτερο timeout)	Upstream timeout ή client disconnect	Retry, αν επιμένει increase timeout

Γιατί όχι 503?

Δεν παράγεται από το Estia.API. Αν δεις 503, είναι load balancer / Kubernetes readiness probe.

Retry decision tree¶

              ┌─────────────────┐
              │  Got error?     │
              └────────┬────────┘
                       │
            ┌──────────┴──────────┐
            │                     │
        Status 4xx?            Status 5xx?
            │                     │
   ┌────────┴────────┐    ┌───────┴────────┐
   │                 │    │                │
  401: refresh     422: fix   500: limited  502/504: retry
   token           request    retry         exp backoff
                              + escalate    + jitter
                              if persists

POST/PATCH special case — δες Idempotency παρακάτω.

ProblemDetails envelope (RFC 7807)¶

Κάθε error response έχει Content-Type: application/problem+json και αυτό το shape:

{
  "type": "...",
  "title": "Provider business error",
  "status": 422,
  "detail": "Vehicle ABC-1234 already has an active policy.",
  "instance": "/allianz/contracts/auto-calculate",
  "provider": "Allianz",
  "providerErrorMessage": "Vehicle ABC-1234 already has an active policy.",
  "providerDetailedMessage": "Active policy P-998877 expires 2026-12-31.",
  "category": "business",
  "traceId": "9f3a2b1c-4d5e-6789-abcd-ef0123456789",
  "correlationId": "9f3a2b1c-4d5e-6789-abcd-ef0123456789"
}

Standard fields (RFC 7807)¶

Field	Πάντα παρόν;	Περιγραφή
`type`	Sometimes	URI για κατηγορία (informational, δεν είναι contract)
`title`	✅	Σύντομος, σταθερός τίτλος (πχ "Provider business error")
`status`	✅	HTTP status (mirrors response status)
`detail`	✅	Αναλυτικό μήνυμα (για 422 = upstream message, για 5xx = generic)
`instance`	✅	Request path

Extensions (Estia.API custom)¶

Field	Σε ποιο status	Περιγραφή	Χρήση
`provider`	422, 502, 504	Όνομα provider (Allianz, Orizon, ...)	Logs, dashboards
`providerErrorMessage`	422	Upstream message αυτούσιο	End-user display
`providerDetailedMessage`	422	Συμπληρωματικές πληροφορίες	Logs, support tickets
`providerStatusCode`	502	Upstream HTTP status (αν REST)	Logs, metrics
`category`	All	`business` / `transport` / `timeout` / `unexpected`	Routing σε metrics
`traceId`	All	Server trace ID	Support tickets
`correlationId`	All	Alias του `traceId` (legacy)	Backwards compat

Τι βλέπει ο consumer vs τι είναι κρυμμένο¶

Κατηγορία	Βλέπει consumer	ΔΕΝ βλέπει consumer
422 business	Πλήρες upstream `providerErrorMessage`	—
502 transport	Generic message + `providerStatusCode`	Raw upstream body, internal credentials, URLs
504 timeout	Generic "timed out"	Internal timeout values, retry attempts
500 bug	Generic "internal error" + `traceId`	Stack trace, exception type

Γιατί έτσι: στις transport/timeout περιπτώσεις, το internal info δεν είναι actionable για τον consumer (είναι του Estia.API ή του provider, όχι του consumer). Αν εκθέταμε raw body, θα διέρρεε credentials/URLs/architecture. Το traceId αρκεί για escalation.

Retry strategy¶

Defaults (production-ready)¶

Parameter	Value
Initial delay	1s
Multiplier	2× (exponential)
Max attempts	5
Jitter	±25% (random)
Max delay cap	30s

Επιδέξιες στρατηγικές:

502 / 504: full retry policy. Συνήθως επιτυχία στο 2ο-3ο attempt.
429: σεβάσου Retry-After header (αν στείλει absolute datetime ή delta seconds). Δεν παράγει Retry-After το Estia.API σήμερα (rate limiting δεν εφαρμόζεται γενικά).
500: limited (~2 attempts max). Αν συνεχίζει, στείλε traceId στο support.

Code samples¶

Δες error-handling.md για πλήρη examples σε: - C# / Polly (HTTP client policy) - Node.js / axios-retry (interceptor) - Python / tenacity (decorator)

Idempotency for POST/PATCH¶

Mutating requests χρειάζονται προσοχή

Ένα 502 ή 504 σε POST/PATCH δεν εγγυάται ότι ο upstream δεν δέχτηκε ήδη το request. Μπορεί να έγινε γράψιμο upstream και η απάντηση να χάθηκε. Blind retry δημιουργεί duplicates.

"Check-before-retry" pattern¶

Πριν retry-άρεις mutating call που πήρε 502/504:

Αναζήτηση: κάνε GET με μια εξωτερική αναφορά (πχ external policy reference, AFM + plate, business key)
Αν βρεις την entity → χειρίσου ως success (το request πέρασε upstream)
Αν όχι → safe να retry

Παράδειγμα pseudocode:

try {
    return await api.CreatePolicy(req);
} catch (HttpStatus502Or504) {
    var existing = await api.SearchByExternalRef(req.ExternalRef);
    return existing ?? await api.CreatePolicy(req);  // safe retry only αν όχι existing
}

Per-provider quick reference¶

Όλοι οι 23 providers ακολουθούν τους ίδιους κανόνες status mapping. Παρακάτω quirks/specifics:

Provider	Protocol	Business envelope	Quirks
Allianz	REST	X-Error header + AllianzErrorDto	Codes
Apeiron	SOAP	ThrowOnProblem helper	Stub
Atlanet	SOAP	— (transport only)	Stub
ErgoHellas	SOAP	SAP message types E/A/W/I/S	Codes
Ethniki	SOAP	`filler1='Y'` indicator	Stub
Eurolife	REST	Response code inspection	Stub
Euroins	SOAP	ServiceError με `Level≥Critical`	Codes
Europe	SOAP	— (transport only)	Stub
EuroSos	REST	HTTP 400 → business	Stub
Extra	SOAP	Inline validation errors	Stub
Generali	SOAP	XML `response_status`	Stub
Groupama	REST	HTTP status only	Stub
Interamerican	SOAP	— (transport only)	Stub
Interfast	SOAP	`CheckProviderError` inline	Stub
InterLife ⚠️	SOAP	SOAP fault → 422 (provider-specific)	Stub
Intersalonica	SOAP	Reflection `IsSuccess=false`	Stub
Minetta	SOAP	`Errors[]` envelope	Stub
Mondial ⚠️	SOAP	SOAP fault → 422 (provider-specific)	Stub
Orizon	SOAP	Reflection + `OrizonErrorHelper`	Stub
PersonalIns ⚠️	SOAP	SOAP fault → 422 (provider-specific)	Stub
Soeasy	REST	HTTP status only	Stub
Totalware	REST	`Errors[]` envelope	Codes
Ydrogeios	SOAP	— (transport only)	Stub

⚠️ Σημείωση για InterLife / Mondial / PersonalIns

Αυτοί οι 3 providers κωδικοποιούν business validation μέσα σε SOAP faults (όχι σε response envelope). Άρα ένα FaultException από αυτούς γίνεται 422 (όχι 502). Για τον consumer η διαφορά είναι invisible — απλά παίρνει 422 με providerErrorMessage. Αυτό είναι intentional design.

Για πλήρες matrix με 6 σενάρια × 23 providers, δες provider-error-matrix.md.

Common scenarios — playbook¶

"Παίρνω 422 — τι κάνω;"¶

Δείξε providerErrorMessage στον end-user (είναι localized/actionable)
Logging: provider + category + traceId
Όχι retry — fix το request

"Παίρνω συνεχόμενα 502 — τι κάνω;"¶

Retry με exp backoff (max 5 attempts)
Αν επιμένει >3 φορές, ο upstream είναι κάτω → fallback ή escalate
Στείλε traceId + provider στο support

"Παίρνω 504 σε POST — τι κάνω;"¶

ΟΧΙ blind retry — μπορεί να έχει γίνει partial success upstream
Εφάρμοσε check-before-retry pattern
Αν όχι external ref διαθέσιμη → escalate manually

"Παίρνω 401 — τι κάνω;"¶

Refresh Keycloak token (client_credentials flow)
Retry ένα μόνο attempt με νέο token
Αν συνεχίζει → check credentials στο config

"Παίρνω 500 — τι κάνω;"¶

Μην retry άπειρα (2 attempts max)
Στείλε traceId στο support άμεσα — είναι bug στο Estia.API
Log όλο το ProblemDetails body

Support escalation workflow¶

Από το response, πάρε το traceId (ή correlationId — alias)
Στείλε στο Estia.API support με:
traceId
Provider name (από provider extension)
Τι περίμενες
Τι έλαβες
Timestamp (UTC)
Το support μπορεί να βρει τα logs μέσω traceId σε <1 λεπτό

Δικό σου correlation

Αν έχεις δικό σου request tracing, στείλε header X-Correlation-ID: <your-id> και θα γυρίσει στο response (συνδέει τα δύο tracing systems).

Doc	Τι θα βρεις
Error handling overview	Detailed envelope, code samples, redaction policy
Provider × error matrix	23 providers × 6 scenarios visual table
Per-provider error codes	Enumerated codes ανά provider (4 rich + 19 stubs)
Authentication	Keycloak `client_credentials` flow
Rate limits	Throughput & throttling
Support	Πώς να επικοινωνήσεις