Error Catalog
Every business error code Migo's APIs can return. Codes are strings in the 7000β8099 range and are returned in the errors[] array of the CustomResponse envelope:
{
"success": false,
"message": "Optional human-readable summary",
"errors": [{ "code": "7200", "message": "Card not found in the system." }]
}
The HTTP status is derived from the code by the gateway response interceptor, in this precedence order: 500 (internal) β 404 (not found) β 400 (bad request) β 401 (unauthorized) β 403 (forbidden) β 409 (conflict). A code not classified in any set defaults to 500.
This catalog is generated from MigoCodeErrors and MigoErrorMessages in @migo-payments/ali-common-tl (src/errors/error.enum.ts and src/errors/error.ts). Messages are the exact strings returned by the API.
Response envelopeβ
Every Migo API returns responses wrapped in a CustomResponse<T> envelope. The envelope shape is:
interface CustomResponse<T> {
success: boolean;
message?: string;
data?: T;
errors?: { code: string; message: string }[];
}
Note that code is a string (e.g. "7100"), and errors is an array of { code, message } objects. There is no statusCode, error.name, or error.detail field on the wire payload β the name (e.g. USER_NOT_FOUND) is the internal MigoNameErrors key, not part of the response body.
Successβ
{
"success": true,
"message": "ok",
"data": { "...": "..." }
}
Errorβ
{
"success": false,
"message": "Validation failed",
"errors": [
{
"code": "7100",
"message": "User not found in the system."
}
]
}
Status code mappingβ
| HTTP status | When it's returned |
|---|---|
200 OK | Success (including async jobs that return a batch/job id in the body) |
201 Created | Resource created (e.g. statement creation accepted) |
204 No Content | Success, no body |
400 Bad Request | Body validation failed |
401 Unauthorized | Missing / expired / invalid JWT |
403 Forbidden | Authenticated but permission denied |
404 Not Found | Resource does not exist |
409 Conflict | Resource state conflict |
422 Unprocessable Entity | Semantic validation failed (e.g. card expired) |
500 Internal Server Error | Migo bug β please report with the request timestamp and details |
502 Bad Gateway | Upstream processor unreachable |
503 Service Unavailable | Scheduled maintenance or partial outage |
504 Gateway Timeout | Upstream processor timeout |
General & Parameters (7000β7099)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7000 | CHECK_PARAMETERS | 400 | Check the parameters provided. |
7001 | GREATER_THAN_ZERO | 400 | The amount must be greater than zero. |
7002 | INVALID_FORMAT_AMOUNT | 400 | Invalid amount format. |
7003 | CONSULT_WITH_SUPPORT | 500 | Please contact support for assistance. |
7004 | SERVICES_NOT_FOUND | 404 | Required services not found. |
7005 | PROCESSOR_NOT_FOUND | 404 | Payment processor not found. |
7006 | EXTERNAL_ID_ALREADY_EXISTS | 409 | External ID already exists. |
7007 | ERROR_GETTING_ACTIONS | 500 | Error retrieving actions. |
7008 | ERROR_DATE_RTU | 500 | The RTU (Real-Time Update) date is invalid. The update date must be within the last 6 months from the current date. |
7009 | ERROR_CAN_INVOICE_PARAM | 500 | Error with invoice parameters. |
7010 | NOT_FOUND | 404 | Not found, verify endpoint |
7011 | ERROR_CREATE_TERMINAL_PROCESSOR | 500 | Error creating terminal processor, please verify data and try again. |
7012 | ERROR_UPDATE_TERMINAL_PROCESSOR | 500 | Error updating terminal processor, please verify data and try again. |
7013 | TERMINAL_PROCESSOR_NOT_FOUND | 404 | Terminal processor not found |
7014 | TERMINAL_PROCESSOR_EMPTY | 404 | Terminal does not have a terminal processor |
7015 | TERMINAL_PROCESSOR_ALREADY_EXISTS | 409 | Terminal processor already exists |
7016 | TERMINAL_PROCESSOR_INACTIVE | 409 | Terminal processor is inactive, if you want to activate it please contact support. |
Users, Auth & OTP (7100β7199)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7100 | USER_NOT_FOUND | 404 | User not found in the system. |
7101 | USER_ALREDY_EXIST | 409 | User already exists in the system, check your username. |
7102 | USER_DOCUMENT_NOT_FOUND | 404 | User document not found. |
7103 | ERROR_CREATE_USER_DOCUMENT | 500 | Error creating user document. |
7104 | ERROR_READ_USER_FILE | 500 | Error reading user file. |
7105 | ERROR_CREATE_LEAD | 500 | Error creating lead. |
7106 | ERROR_FIND_USER_BY_DOCUMENT | 500 | Error finding user by document. |
7107 | VERIFY_DOCUMENT_TYPE | 400 | Please verify the document type. |
7108 | ACCOUNT_NOT_FOUND | 404 | Account not found in the system. |
7109 | ERROR_CREATING_NEW_ACCOUNT | 500 | Error creating new account. |
7110 | ERROR_CREATING_INVITATION_CODE | 500 | An error occurred while creating the invitation code, check the branch status |
7111 | ERROR_PASSWORD_NOT_MATCH | 400 | Passwords do not match, please check and try again. |
7112 | ERROR_MIN_LENGTH_PASSWORD | 400 | Please check that the string length has the indicated number of characters. |
7113 | ERROR_LOWERCASE_PASSWORD | 400 | Please check that the string contains at least one lowercase letter. |
7114 | ERROR_UPPERCASE_PASSWORD | 400 | Please check that the string contains at least one uppercase letter. |
7115 | ERROR_AT_LEAST_NUMBER_PASSWORD | 400 | Please check that the string contains at least one number. |
7116 | ERROR_AT_LEAST_SYMBOL_PASSWORD | 400 | Please check that the string contains at least one special character. |
7117 | INVALID_PASSWORD | 400 | Invalid password, please check and try again. |
7118 | ERROR_CREATING_USER | 500 | Error creating user, please contact support. |
7119 | ERROR_PREVIOUS_PASSWORD | 409 | You cannot reuse a previous password, please try with a new one. |
7120 | NOT_FOUND_INVITATION_CODE | 404 | Invitation code not found, please check your code and try again. |
7121 | LEAD_ALREADY_REGISTERED | 409 | Lead already registered, please get a new invitation code. |
7122 | TERMS_AND_CONDITIONS_NOT_ACCEPTED | 400 | Please accept the terms and conditions to continue. |
7123 | DOCUMENT_ALREADY_EXIST | 409 | Document already exist, please verify it. |
7124 | ERROR_FINDING_USER | 500 | Error finding user, please check your userId and try again. |
7125 | ERROR_CREATING_USER_APPLICATION | 500 | Error creating user application, please contact support. |
7126 | ERROR_CREATING_AUTH_USER | 500 | Error creating auth user, please contact support. |
7127 | ERROR_USER_IS_ACCOUNT | 400 | User is an account, access denied. |
7128 | USERNAME_NOT_FOUND | 404 | User not found, please check your username and try again. |
7129 | APPLICATION_USER_NOT_FOUND | 404 | Application user not found, please check your user and try again. |
7130 | LEAD_NOT_FOUND | 404 | Lead not found, please check your lead information and try again. |
7131 | INVALID_OTP_PURPOSE | 400 | Invalid OTP purpose, please check the purpose and try again. |
7132 | INVALID_OTP | 401 | Invalid OTP, please check the OTP and try again. |
7133 | OTP_NOT_FOUND | 404 | OTP not found, please check the OTP and try again. |
7134 | OTP_ALREADY_USED | 409 | OTP has already been used, please request a new OTP. |
7135 | OTP_EXPIRED | 400 | OTP has expired, please request a new OTP. |
7136 | OTP_REQUEST_FAILED | 400 | Failed to request OTP, please try again later. |
7137 | ERROR_VALIDATING_USER | 500 | Error validating user, please contact support. |
7138 | ERROR_ACCESS_LOGIN | 500 | An error occurred while logging in, please try later. |
7139 | USER_SUSPENDED | 403 | You have exceeded the number of login attempts, your user has been temporarily suspended |
7140 | ERROR_FINDING_SUSPENSION | 500 | Error finding suspension, check the users ms |
7141 | ERROR_CREATING_SUSPENSION | 500 | Error creating suspension, check the users ms |
7142 | ERROR_LOGOUT | 500 | Error logging out, check your token |
7143 | UNAUTHORIZED_ACCESS_USER | 401 | Unauthorized access user, please check your credentials. |
7144 | FORBIDDEN_ACCESS_USER | 403 | Your user does not have permission to access this resource |
7145 | INVALID_USER_ACCESS_TOKEN | 500 | Invalid user access token, check your token |
7146 | INVALID_USER_REFRESH_TOKEN | 500 | Invalid user refresh token, check your refresh token |
7147 | INVALID_USER_SIGNATURE | 401 | Invalid user signature, check your token |
7148 | EXPIRED_USER_TOKEN | 400 | Expired user token, please use refresh token or login again. |
7149 | EXPIRED_USER_REFRESH_TOKEN | 400 | Expired user refresh token, please login again. |
7150 | ERROR_CREATING_AUTH_USER_ROLE | 500 | Error creating auth user role, please contact support. |
7151 | ERROR_CREATING_AUTH_USER_PERMISSION | 500 | Error creating auth user permission, please contact support. |
7152 | ERROR_UPDATING_AUTH_USER_PERMISSION | 500 | Error updating auth user permission, please contact support. |
7153 | ERROR_UPDATING_AUTH_USER_ROLE | 500 | Error updating auth user role, please contact support. |
7154 | ERROR_FINDING_AUTH_USER_ROLE | 500 | Error finding auth user role, please contact support. |
7155 | ERROR_FINDING_AUTH_USER_PERMISSION | 500 | Error finding auth user permission, please contact support. |
7156 | AUTH_USER_ROLE_NOT_FOUND | 404 | Auth user role not found, check names |
7157 | AUTH_USER_PERMISSION_NOT_FOUND | 404 | Auth user permission not found, check names |
7158 | ROLE_ALREADY_EXIST | 409 | Role already exists, check roles |
7159 | USER_PERMISSION_ALREADY_EXIST | 409 | User permission already exist, please verify data and try again. |
7160 | ERROR_REGISTERING_FCM_TOKEN | 500 | Error registering FCM token, please verify data and try again. |
7161 | ERROR_REMOVING_FCM_TOKEN | 500 | Error removing FCM token, please verify data and try again. |
7162 | INVALID_REGISTRATION_TOKEN | 400 | Invalid registration token, please verify data and try again. |
7163 | FCM_TOKEN_NOT_FOUND | 404 | FCM Token not found, please renew the device token |
7164 | ERROR_UPDATING_USER_PASSWORD | 500 | Error updating user password, please verify data and try again. |
7165 | PASSWORD_NOT_PROVIDED | 500 | Password not provided, please provide a password. |
7166 | PASSWORDS_DO_NOT_MATCH | 500 | Passwords do not match, please check and try again. |
7167 | ERROR_UPLOADING_PROFILE_IMAGE | 400 | Error uploading profile image, please try again later. |
7168 | ERROR_GETTING_USER_PROFILE | 400 | Error getting user profile, please check your userId and try again. |
7169 | ERROR_UPDATING_USER_PROFILE | 500 | Error updating user profile, please try again later. |
7170 | ERROR_FETCHING_PROFILE_DATA | 500 | Error fetching profile data, please try again later. |
7171 | INVALID_USER_STATUS | 409 | User status is invalid, if you want to activate it please contact support. |
7172 | EXPIRED_USER_PASSWORD | 409 | User password is expired, please reset your password and try again. |
7173 | SDK_NOT_VALID | 500 | Invalid sdk. |
7186 | USER_DOCUMENT_DUPLICATED_IN_MERCHANT | 409 | More than one user is registered with this document, please contact support. |
Cards (7200β7299)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7200 | CARD_NOT_FOUND | 404 | Card not found in the system. |
7201 | INVALID_CARD_ACCESS | 400 | Unauthorized card access. Please verify the information entered. |
7202 | ALREADY_ACTIVED | 409 | Card is already activated. |
7203 | ALREADY_BLOCKED | 409 | Card is already blocked. |
7204 | ALREADY_UNLOCKED | 409 | Card is already unlocked. |
7205 | INCORRECT_PIN | 400 | Incorrect PIN entered. |
7206 | CARD_EXPIRED | 400 | The card has expired. |
7207 | CARD_NOT_CREATED | 500 | Error creating the card. |
7208 | CARD_ALREADY_ASSIGNED | 409 | Card is already assigned to a user. |
7209 | CARD_ALREADY_LINKED | 409 | Card is already linked to an account. |
7210 | CARD_NOT_UPDATED | 500 | Error updating card information. |
7211 | ERROR_CREATING_CARD | 500 | Error while creating card. |
7212 | CARDS_NOT_FOUND | 404 | The user does not have any cards. |
7213 | INVALID_STATUS_CARD | 400 | The card status is invalid. Kindly verify that your card is active |
7214 | ERROR_GETTING_CARD | 500 | Error getting card, please check your cardId and try again. |
7215 | ERROR_GETTING_USER_CARDS | 500 | Error getting user cards, please check your userId and try again. |
7216 | ERROR_CREATING_CARD_USER_PERMISSION | 500 | Error creating card user permission, verify ids and names and try again. |
7217 | ERROR_UPDATING_CARD_USER_PERMISSION | 500 | Error updating card user permission, verify ids and names and try again. |
7218 | ERROR_FINDING_CARD_USER_PERMISSION | 500 | Error finding card user permission, verify ids and names and try again. |
7219 | CARD_USER_PERMISSION_NOT_FOUND | 404 | Card user permission not found, verify ids and names and try again. |
7220 | THIRD_PARTY_CARD_NOT_FOUND | 404 | Third party card not found, please verify suffix, username or id and try again. |
7221 | ERROR_CREATING_THIRD_PARTY_CARD | 500 | Error creating third party card, please verify data and try again. |
7222 | THIRD_PARTY_CARD_ALREADY_ASSIGNED | 409 | Third party card already exist, please verify suffix, username and try again. |
7223 | CARD_ASSOCIATED_BELONGS_TO_THE_USER_WHO_MADE_THE_REQUEST | 409 | You cannot associate cards that already belong to the user |
7224 | ERROR_CREATING_VIEW_TOKEN | 500 | Error creating view token, please verify data and try again. |
7225 | VIEW_TOKEN_NOT_FOUND | 404 | View token not found, please verify data and try again. |
7226 | ERROR_UNLINKED_THIRD_PARTY_CARD | 500 | Error unlinked third party card, please verify data and try again. |
7227 | ERROR_UPDATING_THIRD_PARTY_CARD | 500 | Error updating third party card, please verify data and try again. |
Transfers & Payments (7300β7399)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7300 | ERROR_CREATING_TRANSFER | 500 | Error while creating the transfer. |
7301 | ERROR_UPDATING_TRANSFER | 500 | Error while updating the transfer. |
7302 | ERROR_GETTING_HISTORY | 500 | Error retrieving transaction history. |
7303 | INSUFFICIENT_FUNDS | 400 | Insufficient funds to complete the transaction. |
7304 | INVALID_TRANSFER_STATUS | 400 | Invalid transfer status. |
7305 | ERROR_CREATING_TRANSFER_TYPE | 500 | Error creating transfer type. |
7306 | CARD_TRANSFER_NOT_FOUND | 404 | Card transfer not found. |
7307 | ERROR_CREATING_TERMINAL_PAYMENT | 500 | Error creating terminal payment. |
7308 | ERROR_TERMINAL_PAYMENT_STATUS | 500 | Error retrieving terminal payment status. |
7309 | ERROR_UPDATING_TERMINAL_PAYMENT | 500 | Error updating terminal payment. |
7310 | CARD_TRANSFER_DATE_NOT_VALID | 403 | The request is no longer valid because it must be completed within the same calendar day. |
7311 | TOPUP_REASON_TOO_LONG | 400 | The reason for the recharge is very long. |
Terminals, Businesses & Branches (7400β7499)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7400 | TERMINAL_NOT_FOUND | 404 | Terminal not found. |
7401 | TERMINAL_INACTIVE | 400 | Terminal is inactive. |
7402 | TERMINAL_PAYMENT_NOT_FOUND | 404 | Terminal payment not found. |
7403 | ERROR_CREATING_TERMINAL | 500 | Error creating terminal. |
7404 | ERROR_UPDATING_TERMINAL | 500 | Error updating terminal. |
7405 | ERROR_CREATING_COMMERCE_CONFIG | 500 | Error creating commerce configuration. |
7406 | ERROR_CREATING_COMMERCE | 500 | Error creating commerce. |
7407 | COMMERCE_OR_USER_NOT_FOUND | 404 | Commerce or user not found. |
7408 | BUSINESS_NOT_FOUND | 404 | Business not found. |
7409 | ERROR_CREATING_BRANCH | 500 | Error creating branch, please contact support. |
7410 | BRANCH_NOT_FOUND | 404 | Branch not found |
7411 | ERROR_CREATING_BRANCH_ACCOUNT | 500 | An error occurred while creating the branch account, check the branch status and the existence of the account |
7412 | BRANCH_ACCOUNT_NOT_FOUND | 404 | The branch account not found, please verify status branch |
7413 | TERMINAL_ALREADY_LINKED | 409 | Terminal already linked, please get a new terminal. |
7414 | BUSINESS_ALREADY_EXISTS | 409 | Business already exists, verify data and try again. |
7415 | BRANCH_ALREADY_EXISTS | 409 | Branch already exists, verify data and try again. |
7416 | BRANCH_AUTH_USER_NOT_FOUND | 404 | AuthUserId provided dont exists in branch auth user, please verify information. |
7417 | BRANCH_AUTH_USER_OWNER_NOT_FOUND | 404 | Branch provided do not have a owner, please verify information. |
7418 | ERROR_FINDING_BRANCH_AUTH_USER | 500 | Error getting branch auth user, please contact support. |
7419 | TERMINAID_OR_DEVICEID_ARE_MISSING | 400 | Terminal ID or Device ID are missing, please verify data and try again. |
Settlements & Regime (7500β7599)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7500 | ERROR_CREATING_SETTLEMENT | 500 | Error creating settlement. |
7501 | SETTLEMENT_NOT_FOUND | 404 | Settlement not found. |
7502 | ERROR_UPDATING_SETTLEMENT | 500 | Error updating settlement. |
7503 | REGIME_NOT_VALID | 500 | Invalid tax regime. |
7504 | REGIME_NOT_FOUND | 404 | Tax regime not found. |
7505 | ERROR_CREATING_REGIME | 500 | Error creating tax regime. |
7506 | ERROR_CREATING_ACCOUNT_CHANGE | 500 | Error creating account change. |
7507 | DUPLICATE_SETTLEMENT | 500 | A settlement for current terminal payment already exists |
7508 | CONFIG_NOT_FOUND | 404 | Config not found |
7509 | CALLBACK_NOT_FOUND | 404 | Callback not found, please verify data and try again. |
7510 | ERROR_GETTING_UNSETTLED_TERMINAL_PAYMENTS | 500 | Error getting unsettled terminal payments, please verify data and try again. |
Clients, Roles, Permissions & Files (7600β7699)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7600 | ERROR_CREATING_CLIENT | 500 | Error creating client, please contact support. |
7601 | ERROR_AUTHENTICATION_FAILED | 500 | Authentication failed, please check your credentials. |
7602 | UNAUTHORIZED_ACCESS | 401 | Unauthorized access, please check your credentials. |
7603 | EXPIRED_TOKEN | 400 | Token expired, please use refresh token or login again. |
7604 | INVALID_SIGNATURE | 401 | Invalid signature, please check your token. |
7605 | INVALID_REFRESH_TOKEN | 400 | Invalid refresh token, login again. |
7606 | INVALID_ACCESS_TOKEN | 400 | Invalid access token, please check your token. |
7607 | CLIENT_NOT_FOUND | 404 | Client not found, please check your merchant. |
7608 | ERRROR_CREATING_PERMISSION | 500 | No message registered β falls back to 7003 (contact support). |
7609 | ERROR_CREATING_ROLE | 500 | Error creating role, please contact support. |
7610 | ERROR_CREATING_ROLE_PERMISSION | 500 | Error creating role permission, please contact support. |
7611 | ROLES_NOT_FOUND | 404 | One or more roles not found, please verify names. |
7612 | PERMISSIONS_NOT_FOUND | 404 | One or more permissions not found, please verify names. |
7613 | ROLE_PERMISSIONS_NOT_FOUND | 404 | Role permissions not found, please contact support. |
7614 | CLIENT_ROLE_NOT_FOUND | 404 | Client role not found, please contact support. |
7615 | CLIENT_ROLE_FORBIDDEN | 403 | You do not have permission to access this resource. |
7616 | KEYS_EXPIRED | 400 | The keys have expired, please rotate them. |
7617 | ERROR_UPDATING_ROLE | 500 | Error updating role, please contact support. |
7618 | INVALID_SIGNATURE_KEYS | 400 | The signature keys are invalid, please rotate keys and login again. |
7619 | ERROR_UPLOADING_FILE | 500 | Error uploading file, please try again later. |
7620 | INVALID_FILE_TYPE | 500 | Invalid file type, please upload a valid file. |
7621 | NO_SOCIALS_PROVIDED | 400 | No social media links provided, please provide at least one social media link. |
7622 | INVALID_SOCIAL_URL | 400 | Invalid social media URL provided, please check the URL format. |
7623 | ERROR_UPLOADING_SOCIALS | 400 | Error uploading social media links, please try again later. |
7624 | ERROR_SAVING_SOCIALS | 500 | Error saving social media links, please try again later. |
7625 | ERROR_FETCHING_COMMERCE_DOCS | 500 | Error fetching commerce documents, please try again later. |
7626 | MONTH_INVALID | 400 | The month is invalid. It must be a value between 01 and 12. |
7627 | YEAR_INVALID | 400 | The year is invalid. It must be a valid year. |
7628 | FILE_SIZE_LIMIT_EXCEEDED | 400 | The file size exceeds the maximum allowed limit of 16 MB. |
7629 | INVALID_EXCEL_FILE_TYPE | 400 | Invalid file type. Only Excel files (.xlsx, .xls) are allowed. |
7630 | FILE_IS_EMPTY | 400 | The file cannot be empty |
Project Config & App Integrity (7700β7799)β
| Code | Name | HTTP | Message |
|---|---|---|---|
7700 | PROJECT_CONFIG_NOT_FOUND | 404 | Project config not found |
7701 | FORMS_NOT_FOUND | 500 | Project forms not found |
7702 | FORM_DETAIL_NOT_FOUND | 404 | Form details not found |
7703 | ERROR_UPDATING_PROJECT_CONFIG | 500 | Error updating project config, please contact support. |
7704 | ERROR_CREATING_PROJECT_CONFIG | 500 | Error creating project config, please contact support. |
7705 | MERCHANT_ALREADY_LINKED | 409 | Merchant already linked, please get a new merchant or verify it. |
7706 | APP_INTEGRITY_VALIDATION_FAILED | 403 | Unrecognized app version. |
7707 | DEVICE_INTEGRITY_VALIDATION_FAILED | 403 | Unrecognized device integrity status. |
7708 | LICENSING_INTEGRITY_VALIDATION_FAILED | 403 | Unrecognized licensing status. |
7709 | INTEGRITY_TOKEN_EXPIRED_OR_INVALID | 401 | Integrity token has expired or is invalid. |
7710 | INTEGRITY_INVALID_HASH | 400 | Integrity hash is invalid. |
7711 | INTEGRITY_INVALID_APPLICATION_ID | 400 | Integrity application ID is invalid. |
7712 | APP_CONFIG_INTEGRITY_NOT_FOUND | 404 | App config integrity not found. |
7713 | COMMERCE_WEBHOOK_NOT_FOUND | 404 | The webhook does not exist in that commerce. See Payment Webhooks. |
7714 | COMMERCE_WEBHOOK_LIMIT_REACHED | 409 | The commerce reached the maximum number of webhooks (5). |
7715 | COMMERCE_WEBHOOK_INVALID_URL | 400 | The webhook URL must be a public HTTPS URL on port 443. |
7716 | COMMERCE_WEBHOOK_INVALID_HEADERS | 400 | The webhook headers are invalid. |
7717 | COMMERCE_WEBHOOK_DUPLICATE_URL | 409 | The commerce already has a webhook with that URL. |
App (8000β8099)β
| Code | Name | HTTP | Message |
|---|---|---|---|
8000 | APP_ERROR_CREDENTIALS | 401 | Invalid credentials, please try again. |
8001 | APP_NEED_CHANGE_PASSWORD | 401 | Please change your password first. |
8002 | APP_INVALID_ACCESS_TOKEN | 401 | Invalid access token, please try again. |
8003 | APP_INVALID_REFRESH_TOKEN | 401 | Invalid refresh token, please try again. |
8004 | APP_INVALID_OTP | 401 | Invalid OTP, please try again. |
8005 | APP_EMAIL_ALREADY_EXISTS | 409 | Email already exists, please try with another email. |
8006 | APP_USER_NOT_FOUND | 404 | User not found, verify id |
8007 | APP_PARTNER_NOT_FOUND | 404 | Partner not found, verify id |
8008 | APP_PERMISSIONS_NOT_FOUND | 404 | Permissions assigned not found, assign permissions for this user. |
8009 | APP_ERROR_USERS_FETCH | 500 | Invalid query parameters or partner ID not found |
8010 | APP_STATUS_INVALID | 400 | Invalid user status |
8011 | APP_USER_SUSPENDED | 403 | User suspended |
8012 | APP_USER_NOT_CREATED | 400 | User not created, please try again. |
8013 | APP_ERROR_CREATING_PERMISSIONS | 500 | Permission not created, please try again. |
8014 | APP_ERROR_GETTING_PERMISSIONS | 500 | Error retrieving permissions, please try again. |
8015 | APP_ERROR_ASSIGN_PERMISSIONS | 500 | Error when trying assign permissions for user. |
8016 | APP_PERMISSIONS_ALREADY_ASSIGNED | 409 | One or more permissions already assigned by this user for partnerId |
8017 | APP_ERROR_FINDING_ASSIGNED_PERMISSIONS | 500 | Error when finding assigned permissions for this user |
8018 | APP_USER_INACTIVE | 403 | User is inactive |
8019 | APP_USER_BLOCKED | 403 | User blocked |
8020 | APP_INVALID_OTP_PURPOSE | 500 | Invalid OTP purpose. |
8021 | APP_OTP_REQUIRED | 400 | OTP is required. |
8022 | APP_TOKEN_INVALID | 401 | Token is invalid. |
8023 | APP_CARDHOLDER_NOT_FOUND | 404 | Cardholder not found, check information |
8024 | APP_TEMPORARY_PASSWORD_EXPIRED | 409 | The users temporary password has expired; please request a new one from support. |
8025 | APP_PROCESS_NOT_CREATED | 409 | Process not created |
8026 | APP_PROCESS_NOT_FOUND | 404 | Process not found |
8027 | APP_PROCESS_NOT_UPDATED | 409 | Process not updated |
8028 | APP_ERROR_PROCESS | 500 | Error processing request |
8029 | APP_CLIENT_BALANCE_NOT_FOUND | 404 | Client balance not found |
8030 | APP_CLIENT_BALANCE_ALREADY_EXISTS | 409 | Client balance already exists |
8031 | APP_CLIENT_BALANCE_NOT_UPDATED | 500 | Client balance not updated |
8032 | APP_ERROR_CLIENT_BALANCE | 500 | Error client balance |
8033 | APP_INSUFFICIENT_FUNDS_IN_CLIENT_ACCOUNT | 409 | Insufficient funds in client account |
8034 | APP_PROCESS_NOT_PENDING | 500 | Process not pending |
8035 | APP_PROCESS_NOT_APPROVED | 500 | Process not approved |
8036 | APP_PROCESS_NOT_REJECTED | 500 | Process not rejected |
Notesβ
- The stable identifier is the error name (the
MigoNameErrorskey, e.g.CARD_NOT_FOUND). Each name maps to a fixed numericcode. Branch your client logic oncode, but treat the name as the canonical registry key. - Codes are strings, not integers β compare them as strings (
"7200", not7200). - New codes are added over time. Treat unknown codes as generic errors and retry only when the HTTP status is retriable (e.g.
503/504). - A handful of codes have no message registered in
MigoErrorMessages; the API falls back to7003(CONSULT_WITH_SUPPORT, "Please contact support for assistance.") for those.
Payment Link / Middleware error codesβ
Migo uses two distinct business error code spaces depending on the API you are calling. The Wallet Gateway surfaces a string code inside the errors[] array of the CustomResponse envelope (the 7000β8099 ranges documented above); the Middleware uses a separate envelope (ErrorResponseDto) with its own code, nested under error.code. The numeric ranges do not overlap and the field path differs.
code, not ownCodeThe Middleware error envelope nests the business code under error.code (string). Verified against the real handler: it builds the error object with getMigoErrorByOwnCode(), which returns { code, name, description } β there is no ownCode field in the response.
The Middleware (Payment Links, tokenization, payments) exposes the business error in the code field (nested under error.code) rather than errors[].code. Its shape is:
interface ErrorResponseDto {
message?: string;
error?: {
code?: string; // Migo business error code (string, e.g. "2002")
name?: string; // short error name (e.g. "INVALID_TRX_ID")
description?: string; // human-readable description
};
}
The codes are short numeric strings (e.g. "2002") and do not overlap with the 7000β8099 range above because they live in a different envelope and field path (a nested error.code, not an errors[].code array).
When you wrap calls to both surfaces in the same client, branch on the field path:
const code = response?.errors?.[0]?.code ?? response?.error?.code;
Transaction lifecycle (2000β2099)β
These come back from the create and lookup operations on the Middleware transaction surface β POST /transactions (create) and GET /transactions (lookup).
| HTTP | code | Cause | What to do |
|---|---|---|---|
| 404 | 2000 | Transaction not found for the given uid (GET /transactions?uid=) | Verify the identifier; the transaction may have expired or belong to another client. |
| 400 | 2002 | Generic creation error | Retry; if it persists, contact support with the request payload and any uid returned. |
| 409 | 2003 | amount is outside clientConfig.createTransactionRangeAmount, or a value in processorAmount exceeds amount | Adjust amount to fall in the configured range; ensure each processorAmount value is <= amount. |
| 400 | 2004 | End customer (userId) is blocked for this client | Blocked users cannot transact β unblock through Migo before retrying. |
| 400 | 2005 | End customer is suspended for this client | Wait for the suspension to expire or ask Migo to remove it. |
| 400 | 2006 | End customer is excluded for this client | Excluded users cannot transact for this client at all. |
| 401 | 2007 | Invalid credentials on the hook endpoint (POST /transactions-hook) β the body's privateKey/publicKey pair does not match a registered application | This code does not apply to POST /transactions (authenticated with a bearer token via the gateway authorizer, not privateKey/publicKey). Verify the hook credentials with your Migo contact. |
Dismiss / cancellation (4000β4099)β
Returned by the Alternative Payments dismiss endpoint β POST /api/v1/integrations/transactions/{transactionId}/dismiss. See Dismiss transaction for the eligible-state matrix.
| HTTP | code | Cause | What to do |
|---|---|---|---|
| 409 | 4020 | Transaction status is not eligible for dismissal (APPROVED, DENIED, EXPIRED, DISMISSED) | Re-read the transaction status before dismissing; only CREATED, USED, and IN_PROGRESS are eligible. |
| 405 | 4021 | The processor does not allow dismissal (no cancel hook) for an IN_PROGRESS transaction | Not all rails support cancellation; let the transaction expire on its own. |
Validation / configuration (5000β5099)β
These are returned when the request body is malformed or references something that does not exist in Migo configuration.
| HTTP | code | Cause | What to do |
|---|---|---|---|
| 409 | 5000 | Required fields missing or invalid body shape | Verify amount, userId, channel, client are present with the correct types. |
| 409 | 5004 | client slug not found in Migo configuration | Confirm the slug spelling. If the client should exist, ask Migo to create or activate it. |
Reading the error code defensivelyβ
type MiddlewareError = {
message?: string;
error?: {
code?: string; // Migo business error code (string)
name?: string;
description?: string;
};
};
const code = err?.error?.code; // Middleware (nested, string)
const fallback = err?.errors?.[0]?.code; // Gateway (string)
switch (String(code ?? fallback)) {
case '2007': return 'Invalid Migo credentials';
case '2003': return 'Amount out of allowed range';
case '5004': return 'Unknown client slug';
case '7200': return 'Card not found';
// ...
}
Retry semanticsβ
| Error class | Retry? | Strategy |
|---|---|---|
| Network timeout | Yes | Exponential backoff |
500 / 502 / 504 | Yes | Exponential backoff, cap at 3 retries |
503 | Yes | Exponential backoff with long ceiling (up to 5 min) |
400 / 422 | No | Fix the request |
401 | No (refresh instead) | Refresh token, then retry |
403 / 404 / 409 | No | Do not retry |
Client patternβ
async function call<T>(fn: () => Promise<T>, attempt = 0): Promise<T> {
try {
return await fn();
} catch (err) {
const status = err.response?.status;
if (status === 401) {
await refreshToken();
return call(fn, attempt + 1);
}
if ([500, 502, 503, 504].includes(status) && attempt < 3) {
const wait = 2 ** attempt * 500;
await new Promise(r => setTimeout(r, wait));
return call(fn, attempt + 1);
}
throw err;
}
}
Reporting issuesβ
When opening a support ticket include:
- The request timestamp in UTC (Migo correlates it to the internal trace)
- Full request URL, method, and headers (redact the Bearer token)
- Request body (redact PANs and CVVs)
- Full response body