Error Handling

Ergani does not publish a complete error code catalog

There is no list of numbered error codes. Errors come back as 400 Bad Request with a human-readable message string in Greek. The table below covers every error message documented in the official manuals and the authentication errors. For any other message, read it literally — it's describing the specific validation rule that failed — and do not retry without changing the request.

How to read an error response

{
  "message": "Για το Παράρτημα: 0\\nΤο ΑΦΜ δεν αντιστοιχεί στον συνδεδεμένο εργοδότη."
}

• HTTP status 400 → the request was rejected. Nothing was recorded. No protocol was issued.
• message → Greek text describing exactly what's wrong, often naming the specific branch (Παράρτημα) or field involved.

Documented errors

HTTP status	message (or condition)	Meaning	Root cause	Fix	Retry?
400	Το ΑΦΜ δεν αντιστοιχεί στον συνδεδεμένο εργοδότη.	The employee ΑΦΜ in f_afm, or the employer ΑΦΜ in f_afm_ergodoti, doesn't match the employer your credentials are connected to.	Wrong ΑΦΜ, or testing production ΑΦΜs against the trial environment (or vice versa).	Use the ΑΦΜ of the employer/employee actually linked to your account in this environment.	No — fix the data first.
400	"message": "Service Code is not authenticated to specific User" (from WebServices/ExecuteService)	Your account isn't authorized for the requested ServiceCode.	The service is restricted to certain user types/roles.	Confirm the service is listed for your account via WebServices/ServicesList.	No.
401	Unauthorized on any endpoint except Authentication	Access token is invalid or expired.	Token expired (3h lifetime), or wasn't sent.	Call Authentication/Refresh, then retry the original request once.	Yes, once, after refreshing.
401	Unauthorized on Authentication/Refresh	Refresh token is invalid or expired (7d lifetime).	Too much time has passed since the last Authentication call.	Call Authentication again with credentials.	Yes, once, after re-authenticating.
—	Response header api-token-expired: true	Same as 401 above — the access token has expired.	Same as above.	Same as above.	Yes, once, after refreshing.
429	Too Many Requests	You've exceeded Ergani's rate limit for authentication calls.	Calling Authentication or Authentication/Refresh on every request instead of reusing tokens.	Stop re-authenticating per request — see Authentication.	No — fix the calling pattern, then back off before retrying.

Validation errors not in the table above

WRKCardSE submissions are also rejected for reasons covered in Work Card API Reference and Core Concepts, without a single fixed message string:

• A required field is missing or has the wrong type (e.g. f_type is not "0" or "1").
• f_aitiologia is null but the event is more than 15 minutes late, or f_aitiologia is set but the event is on time.
• f_aitiologia is set to a value other than "001", "002", "003".
• The f_reference_date / f_date combination violates the check-in or check-out rules in Work Card API Reference.

For all of these, message describes the specific problem — treat it as authoritative and adjust the request. None of these are retryable without a change to the payload.

General rule

Status	Retry?
400	No — fix the request.
401 / api-token-expired: true	Yes, once, after refreshing or re-authenticating.
429	No immediate retry — you're being rate-limited because of how you're calling the API, not because of this one request.
5xx	See Production Guide for retry/backoff guidance.

What's next

• Production Guide — retries, logging, and deduplication for production traffic.
• Real-World Scenarios — worked examples of failure handling.