08.03 Error Code Dictionary

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

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

Этот документ описывает internal error codes для MVP.

Error codes нужны, чтобы:

• merchant получал единый безопасный error response;
• merchant webhooks содержали безопасную причину failed/rejected/canceled transaction;
• Back Office показывал consistent error information;
• provider raw errors не раскрывались merchant users;
• support/platform users могли расследовать transaction через mapping.

2. Где показываются error codes

Error codes показываются в:

• Merchant API response;
• Merchant webhook payload, если transaction status связан с ошибкой / rejection / cancellation;
• Merchant Portal / Back Office transaction details;
• Platform Back Office transaction details;
• transaction timeline;
• transaction export, если user имеет permission видеть эти поля.

3. Где error codes не показываются

Error codes не показываются:

• customer на hosted payment form;
• provider-facing requests;
• public provider callback URLs/docs;
• customer-facing generic error screen.

Customer на hosted payment form видит только:

• generic message;
• reference ID.

4. Merchant-facing principle

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

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

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

• real provider error;
• raw provider response;
• provider stack trace;
• internal exception;
• hidden routing internals;
• provider credentials/config.

5. Platform visibility

Platform user с permission видит:

• internal error code;
• description;
• category;
• provider raw error, если есть;
• provider error -> internal error mapping;
• source;
• timeline event;
• raw payload/request/response, если permission позволяет.

6. Error code fields

Каждый error code должен иметь:

• code;
• category;
• description;
• recommended HTTP status;
• visibility notes, если нужно.

Field retryable в MVP не нужен.

Retry behavior может быть определен development team отдельно, если понадобится в API docs.

7. Categories

Error categories:

• VALIDATION;
• AUTH;
• CONFIGURATION;
• ROUTING;
• VELOCITY;
• PROVIDER;
• CALLBACK;
• EXPIRED;
• CANCELED;
• WEBHOOK;
• SYSTEM.

8. Validation errors

Code	Category	Description	Recommended HTTP status
VALIDATION_ERROR	VALIDATION	Request validation failed.	400
MISSING_REQUIRED_FIELD	VALIDATION	Required field is missing.	400
INVALID_FIELD_VALUE	VALIDATION	Field value is invalid.	400
DUPLICATE_TRANSACTION_ID	VALIDATION	Transaction with this transactionId already exists.	409
INVALID_AMOUNT	VALIDATION	Amount is invalid.	400
INVALID_CURRENCY	VALIDATION	Currency is invalid.	400
INVALID_WEBHOOK_URL	VALIDATION	Webhook URL is invalid.	400
INVALID_REDIRECT_URL	VALIDATION	Redirect URL is invalid.	400

9. Auth/signature errors

Code	Category	Description	Recommended HTTP status
AUTHENTICATION_FAILED	AUTH	Authentication failed.	401
INVALID_SIGNATURE	AUTH	Request signature is invalid.	401
API_KEY_REVOKED	AUTH	API key has been revoked.	401
API_KEY_EXPIRED	AUTH	API key has expired.	401

10. Merchant/configuration errors

Code	Category	Description	Recommended HTTP status
MERCHANT_INACTIVE	CONFIGURATION	Merchant is inactive.	403
BRAND_INACTIVE	CONFIGURATION	Brand is inactive.	403
PAYMENT_METHOD_INACTIVE	CONFIGURATION	Payment method is inactive.	403
PAYMENT_METHOD_NOT_FOUND	CONFIGURATION	Payment method was not found.	404
BRAND_NOT_FOUND	CONFIGURATION	Brand was not found.	404

11. Routing errors

Code	Category	Description	Recommended HTTP status
ROUTING_NOT_FOUND	ROUTING	Routing configuration was not found.	422
NO_MATCHING_ROUTING_RULE	ROUTING	No matching routing rule was found.	422
NO_AVAILABLE_MASTER_MID	ROUTING	No available MASTER MID was found.	422
NO_AVAILABLE_SUB_MID	ROUTING	No available SUB MID was found.	422
ROUTING_EXHAUSTED	ROUTING	Transaction could not be routed.	422

12. Velocity errors

Code	Category	Description	Recommended HTTP status
VELOCITY_LIMIT_EXCEEDED	VELOCITY	Transaction was rejected because velocity limit was exceeded.	422

13. Provider errors

Code	Category	Description	Recommended HTTP status
PROVIDER_ERROR	PROVIDER	Transaction failed due to payment provider error.	502
PROVIDER_TIMEOUT	PROVIDER	Payment provider did not respond in time.	504
PROVIDER_UNAVAILABLE	PROVIDER	Payment provider is unavailable.	503
PROVIDER_REJECTED	PROVIDER	Payment provider rejected the transaction.	422
PROVIDER_INVALID_RESPONSE	PROVIDER	Payment provider returned invalid response.	502

Provider descriptions must stay generic and safe.

Merchant must not see real provider response.

14. Callback processing errors

Code	Category	Description	Recommended HTTP status
CALLBACK_VALIDATION_FAILED	CALLBACK	Provider callback validation failed.	200
CALLBACK_AMOUNT_MISMATCH	CALLBACK	Provider callback amount does not match transaction amount.	200
CALLBACK_CURRENCY_MISMATCH	CALLBACK	Provider callback currency does not match transaction currency.	200
CALLBACK_SIGNATURE_INVALID	CALLBACK	Provider callback signature is invalid.	200
CALLBACK_DUPLICATE	CALLBACK	Provider callback was already processed.	200
CALLBACK_IGNORED	CALLBACK	Provider callback was ignored.	200

Provider callback endpoint should accept callback quickly and respond OK after storing/queueing it.

Business validation errors are stored internally and do not necessarily change HTTP response to provider.

15. Expiration/cancel errors

Code	Category	Description	Recommended HTTP status
TRANSACTION_EXPIRED	EXPIRED	Transaction has expired.	422
PAYMENT_SESSION_EXPIRED	EXPIRED	Payment session has expired.	422
TRANSACTION_CANCELED	CANCELED	Transaction was canceled.	422

16. Webhook delivery errors

Code	Category	Description	Recommended HTTP status
WEBHOOK_DELIVERY_FAILED	WEBHOOK	Webhook delivery failed.	502
WEBHOOK_RETRY_EXHAUSTED	WEBHOOK	Webhook retry attempts were exhausted.	502

These codes are mostly internal/platform/merchant Back Office visibility.

They are not provider-facing.

17. System errors

Code	Category	Description	Recommended HTTP status
INTERNAL_ERROR	SYSTEM	Internal system error occurred.	500
SERVICE_UNAVAILABLE	SYSTEM	Service is temporarily unavailable.	503
PROCESSING_ERROR	SYSTEM	Transaction processing failed due to internal error.	500

System error descriptions must not reveal stack traces or internal exception details.

18. Error codes in Merchant API response

Example:

{
  "errorCode": "DUPLICATE_TRANSACTION_ID",
  "description": "Transaction with this transactionId already exists."
}

Merchant API response should not include provider raw error.

19. Error codes in merchant webhooks

Merchant webhook payload всегда содержит:

• errorCode;
• errorDescription.

Если transaction не связана с ошибкой:

• errorCode = null;
• errorDescription = null.

Merchant webhook payload must not include:

• provider raw error;
• provider raw response;
• internal exception details;
• hidden routing details.

20. Error codes in Back Office

Merchant user can see:

• status;
• error code;
• description.

Platform user with permission can also see:

• provider raw error;
• provider code;
• provider status;
• mapping details;
• raw payload/request/response.

21. Error codes in hosted payment form

Hosted payment form must not show internal error code to customer.

Customer sees:

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

Exact reference ID format is technical/design follow-up.

22. Acceptance Criteria

Error Code Dictionary считается согласованным для MVP, если:

• Error codes показываются в Merchant API response.
• Error codes показываются в merchant webhook payload через errorCode and errorDescription.
• Error codes показываются в Merchant Portal / Back Office transaction details.
• Error codes показываются в Platform Back Office transaction details.
• Error codes могут быть частью timeline/export visibility.
• Error codes не показываются customer на hosted payment form.
• Merchant видит только internal error code + safe description.
• Provider raw errors хранятся отдельно.
• Platform user с permission видит provider raw error and mapping details.
• Каждый error code имеет category.
• Каждый error code имеет recommended HTTP status.
• retryable field не входит в MVP.
• Validation errors описаны.
• Auth/signature errors описаны.
• Configuration errors описаны.
• Routing errors описаны.
• Velocity errors описаны.
• Provider errors описаны.
• Callback processing errors описаны.
• Expiration/cancel errors описаны.
• Webhook delivery errors описаны.
• System errors описаны.

23. Open Questions

Product open questions отсутствуют.

Technical/design follow-up:

1. Уточнить final HTTP status mapping.
2. Определить exact JSON error schema.
3. Определить reference ID format для hosted payment form.
4. Определить provider error -> internal error mapping per provider.
5. Определить where callback validation error codes are stored in callback/timeline model.