03.10 Error Mapping And Error Dictionary

Статус: черновик для обсуждения

1. Назначение документа

Этот документ описывает, как в MVP должна работать система error mapping.

Цель error mapping:

• скрыть real provider responses от merchant users и customers;
• вернуть merchant понятный unified error code и description;
• дать platform/support users достаточно данных для investigation;
• обеспечить consistent error behavior во всех flows;
• не раскрывать provider-sensitive информацию наружу.

2. Где хранится error dictionary

В MVP error dictionary хранится на уровне кода.

Back Office UI для настройки error mapping в MVP не нужен.

Это значит:

• error codes описываются разработчиками;
• provider-specific mapping описывается в provider integration code;
• изменения error dictionary проходят через development/release process;
• platform users не редактируют error dictionary через UI.

В будущем можно рассмотреть UI для управления mapping, но это не входит в MVP.

3. Что видит merchant

Merchant всегда видит только:

• unified internal error code;
• human-readable description.

Merchant не должен видеть:

• real provider error code;
• real provider error message;
• raw provider response;
• provider stack trace;
• internal exception details;
• hidden routing/provider information.

Пример merchant-facing error:

{
  "errorCode": "VELOCITY_LIMIT_EXCEEDED",
  "description": "Transaction was rejected because velocity limit was exceeded."
}

4. Error categories

Error codes должны быть разделены по категориям.

Минимальные категории:

• VALIDATION;
• ROUTING;
• VELOCITY;
• PROVIDER;
• WEBHOOK;
• SYSTEM;
• EXPIRED;
• CANCELED.

Категория нужна для:

• support investigation;
• filtering в Back Office;
• metrics;
• alerting;
• понятной структуры error dictionary в коде.

5. Provider raw error

Provider raw error должен храниться отдельно от merchant-facing error.

Provider raw error может содержать:

• provider error code;
• provider error message;
• provider status;
• raw response;
• raw callback payload;
• validation result;
• mapping result.

Provider raw error видят только platform users с соответствующей permission.

Merchant users и customers не видят provider raw error.

6. Unknown provider errors

Если provider вернул ошибку, которую система не смогла точно замапить, merchant-facing error должен быть generic.

Пример:

PROVIDER_ERROR

Description:

Transaction failed due to payment provider error.

Platform user с permission должен видеть original provider error и то, что mapping был fallback/generic.

7. Descriptions

Для MVP не нужно делать разные descriptions для merchant и platform.

Единый internal error code имеет одну human-readable description.

Разница между merchant и platform views заключается не в description, а в доступности дополнительных technical details:

• merchant видит code + description;
• platform видит code + description + provider/internal details.

8. Merchant webhooks

Error code должен попадать в merchant webhook, если webhook отправляется по transaction status, связанному с error/rejection/failure.

Минимально webhook должен содержать:

• status;
• errorCode, если применимо;
• description, если применимо.

Provider raw error в webhook не отправляется.

9. Hosted payment form error display

Customer на hosted payment form не должен видеть technical error code/details.

Customer должен видеть generic message и reference ID, который можно передать support.

Пример customer-facing message:

Payment could not be completed. Please contact support and provide reference ID: {referenceId}.

Reference ID может быть:

• transaction ID;
• public support reference ID;
• другой безопасный identifier.

Точный формат reference ID должен быть предложен development team.

Customer не должен видеть:

• internal error code;
• provider error;
• routing error;
• velocity details;
• technical validation details.

10. Platform visibility

Platform user с permission должен видеть mapping:

provider error -> internal error code

Platform view должна показывать:

• provider error code;
• provider error message;
• provider raw payload, если permission позволяет;
• mapped internal error code;
• mapped description;
• mapping category;
• mapping source;
• whether fallback/generic mapping was used.

11. Severity

В MVP error severity не нужна.

Не нужно вводить:

• info;
• warning;
• error;
• critical.

Для alerting и monitoring в MVP достаточно category, metrics и конкретных event types.

12. Error mapping in transaction lifecycle

Error mapping применяется в следующих flows:

• deposit request validation;
• routing rejection;
• velocity rejection;
• provider request failure;
• provider callback processing;
• expiration;
• manual cancellation/correction;
• webhook delivery failures;
• system/internal failures.

Каждый transaction-level error должен быть сохранен в transaction details / timeline.

13. Timeline

Transaction timeline должна фиксировать error-related events.

Минимально:

• error occurred;
• error mapped;
• provider error received;
• provider error mapped;
• generic provider error used;
• validation error occurred;
• routing error occurred;
• velocity error occurred;
• system error occurred;
• customer-facing error shown.

Merchant-safe timeline должна показывать only allowed error code/description.

Platform timeline должна показывать full mapping details.

14. Metrics

Error mapping должен поддерживать metrics по:

• error category;
• error code;
• payment method;
• merchant;
• brand;
• provider/SUB MID, если доступно;
• status;
• source.

Это нужно для monitoring и investigation.

15. Acceptance Criteria

Error Mapping считается реализованным для MVP, если:

• Error dictionary хранится в коде.
• Merchant видит только unified error code и description.
• Customer видит generic message и reference ID.
• Provider raw error хранится отдельно.
• Provider raw error доступен только platform users с permission.
• Error codes разделены по категориям.
• Минимальные категории включают VALIDATION, ROUTING, VELOCITY, PROVIDER, WEBHOOK, SYSTEM, EXPIRED, CANCELED.
• Unknown provider error мапится в generic provider error.
• Merchant webhook всегда содержит errorCode и errorDescription.
• Если ошибки нет, errorCode и errorDescription равны null.
• Platform user видит provider error -> internal error mapping.
• Error severity не используется в MVP.
• Timeline фиксирует error-related events.
• Metrics можно строить по error category/code/source.