MTAPI Response Codes

Owned by GT (Unlicensed)
Last updated: Jul 18, 2022 by Jean-Claude Batista (Unlicensed)
9 min read

Status codes provide extra information when a request is made to the MTAPI. The response code will be provided when a request has been successfully completed.

Response codes

Response code can be categorized as follows:

  1. 200s to 500s – one to one as in HTTP status codes

  2. MTAPI statuses start from 601K

  3. Using 601000 as starting number provides us an opportunity to prefix some errors like “ServiceRequestNotFound = 4041001”

  4. Generic reusable MTAPI statuses are in 901000-902999 range

Successful response code

MTAPI end-points should return “OK” (http status 200) result.

Finding MTAPI Status Codes on a Swagger page

On a Swagger page, one or more MTAPI status codes can be viewed in "Response Headers" section, similar to shown below:

Response Headers
{
"cache-control": "no-cache",
"content-length": "123",
"content-type": "application/json; charset=utf-8",
"date": "Tue, 20 Apr 2021 11:28:03 GMT",
"expires": "-1",
"mtapistatus": "-1",
"pragma": "no-cache",
"server": "Microsoft-IIS/8.5",
"x-aspnet-version": "4.0.30319",
"x-powered-by": "ASP.NET"
}

In above case "mtapistatus": "-1", represents “NotSet”. MTAPI statuses are relatively new and not all end-point current set MTAPI status. To find which controllers currently set one or more MTAPI status, see section “MTAPI Controllers with MTAPI Status Codes“.

Warning/Error codes

There are no warnings. It is up to the clients how to use MTAPI statuses, For errors, in general, MTAPI end-point returns “BadRequest” (http status 400) result. In some cases (for example authorization failure) MTAPI throws specific exception (for example, AuthorizationExeption 401). Current MTAPI-client-api though considers all exceptions as MtoaException. Regardless of the success or failure of the call, MTAPI-Status-Codes can be accessed and used as follows:

  • If MTAPI end-point is consumed directly through a REST call then the caller can use HTTP response header value of “MtapiStatus“, which is a comma separated MTAPI Status Code, described in the following sections.

  • If MTAPI end-point is consumed through MTAPI-Client-API then MTAPI-Status-Codes and HTTP-Status of the most recent call, can be accessed through “LastMtapiStatusCodes“ and “LastHttpStatusCode“ properties of the most of the clients under “MTOA.Web.Service.Client“ namespace.

MTAPI Controllers with MTAPI Status Codes

At present, only the following controllers have been changed. Other controllers that are not listed here may not return MTAPI Statuses:

Generic/Reusable “Not Found” Statuses - prefixed with 404 (4041000-404nnnn)

  • ServiceRequestNotFound = 4041001
    4041001 is a generic MTAPI status used in more than one controller. 4041001 is returned when an end-point expects a valid Service Request identifier, however the passed identifier cannot find any Service Request.

  • FileAttachmentNotFound = 4041002
    4041002 is a generic MTAPI status used in more than one controller. 4041002 is returned when an end-point expects a valid file attachment identifier, however the passed identifier cannot find any matching file attachment.

  • ServiceRequestNotFound = 4041001, // not found errors starts with 404 followed by 4 digit code 1001, leaving an opportunity use sub status codes below 1000

  • UserNotFound = 4041003, // not found errors starts with 404 followed by 4 digit code

  • ServiceNotFound = 4041004, // not found errors starts with 404 followed by 4 digit code

  • ServiceSettingNotFound = 4041005

  • ServicePreferenceNotFound = 4041006

  • ClientServiceNotFound = 4041007

  • OrganizationNoFound = 4041008

  • ArtifactNoFound = 4041009

  • ServiceRequestIdNotFound = 4041010

  • DocumentNotFound = 4041011

  • MetadataStructureNotFound = 4041013

  • StructureColumnKeyNameNotFound = 4041014

Generic/Reusable Statuses - can be used in any controller (901000-902999)

  • Operation you performed came across internal error, if you keep seeing error contact your lead or support
    InternalError = 901000

  • Error in MTAPI service setting, contact MTAPI team to get it resolved
    MtapiSettingError = 901001

  • Operation you tried to perform came across argument related error - such as missing argument or invalid value
    ArgumentError = 901002

  • An operation cannot be performed because it requires users to be enrolled in a service
    EnrollmentInServiceRequired = 901003

  • Must be a valid province
    InvalidProvince = 901004

  • In a filter, at least one value is invalid. For further details, refer documentation of an operation where this error occur or contact MTAPI team
    InvalidValueInFilter = 901005

  • CurrentUserId does not belong to a real application user
    UserIdNotBelongingToApplication = 901005

  • Authorization error
    AuthorizationError = 901006

  • ApplicationName is not available
    ApplicationNameNotAvailable = 901006

  • Request context is not available
    RequestContextNotAvailable = 901007

  • User is not enrolled in any service with read user permission
    NoServiceWithReadUserPermission = 901008

App Controller (603000 - 603999)

  • Application information wasn't found.
    ApplicationInfoNotFound = 603000

  • Api Key is null.
    ApiKeyIsNull = 603001

  • Application Key Validation Context is null.
    ApiKeyValidationContextIsNull = 603002

  • Api Key Validation Context Service Id is null.
    ServiceIdNotProvided = 603003

  • Api Key Validation Failed.
    ApiKeyValidationKeyFailed = 603004

Accounts Controller (601000-601999)

  • A null UserActivationContext was provided.

    InvalidUserActivationContext = 601000

  • User activation failed.

    UserActivationFailed = 601001

  • A null RegistrationContext was provided.

    InvalidRegistrationContext = 601002

  • User registration failed.

    UserRegistrationFailed = 601003

  • No email value was provided.

    InvalidEmail = 601004

  • No value was provided for the MBUN.

    InvalidMbun = 601005

  • Account recovery failed.

    InitiateAccountRecoveryFailed = 601007

  • The account recovery id must be higher than zero.

    InvalidAccountRecoveryId = 601008

    The completion of the account recovery failed.

    CompleteRecoveryFailed = 601009

  • The user id must be higher than zero.

    InvalidUserId = 601010

  • A value must be provided.

    InvalidConfirmationCode = 601011

  • Failed to verify a users email.

    FailedToVerifyEmail = 601012

  • Failed to retrieve user enrollments.

    GetEnrollmentsFailed = 601013

  • Cannot associate an internal user to an organization.

    CannotAssociateInternalUserToOrganization = 601014

  • Setting the enrollment key failed.

    SetEnrollmentKeyFailed = 601015

  • Get applied permissions failed.

    GetAppliedPermissionsFailed = 601016

  • AppliedUserServicePermissionDTO cannot be null.

    InvalidAppliedServicePermissionDTO = 601017

  • Applying user service permissions failed.

    ApplyUserServicePermissionsFailed = 601018

Address Controller (602000-602999)

  • The ISO Code wasn't provided.
    MissingCountryIsoCode = 602000

  • Getting the list of all countries failed.
    GetCountriesFailed = 602001

  • Getting a country's information failed.
    GetCountryFailed = 602002

  • Getting a list of Canadian Provinces failed.
    GetCanadianProvincesFailed = 602003

  • Getting a list of subdivisions failed.
    GetCountrySubdivisionsFailed = 602004

  • Getting a Provinces details failed.
    GetCanadianProvinceFailed = 602005

  • A country subdivision code wasn't provided.
    MissingCountrySubdivisionCode = 602006

App Controller (603000-603999)

 

ServiceArtifacts Controller (622000-622999)

ServiceArtifactNotFound = 622000,

ServiceArtifactRetrievalFailed = 622001,

ServiceArtifactCreationFailed = 622002,

ServiceArtifactNotCreated = 622003,

ServiceArtifactUpdateFailed = 622004,

ServiceArtifactNotUpdated = 622005,

ServiceArtifactDeletionFailed = 622006,

ServiceArtifactAlreadyExists = 622007,

Artifacts Controller (604000-604999)

  • InvalidArtifactType = 604001

Invalid Artifact Type

  • UpdatingArtifactFailed = 604002

Updating Artifact Failed

  • DeletingArtifactFailed = 604003

Deleting Artifact Failed

  • RetrievingArtifactFailed = 604004

Retrieving Artifact Failed

  • CreatingArtifactFailed = 604009

Creating Artifact Failed

  • VerifyingArtifactFailed = 604005

Verifying Artifact Failed

  • RetrievingDeletedArtifactFailed = 604006

Trying to retrieve deleted artifact failed

  • GetArtifactsFailed = 604007

Get Artifacts has failed

  • GetArtifactByIdFailed = 604008

Get Artifact by artifact Id has failed

Email Notification Controller (605000-605999)

Note: changes described in this section are under development. Your environment may not have these changes yet.

  • UnsentEmailCheckFailed = 605001
    An attempt failed while trying to identify unsent emails, you may try again or contact support if this fails repetitively.

  • SendEmailNotificationFailed = 605002
    Error while sending email notification, you may try again or contact support if this fails repetitively.

  • EmailVerificationCodeSentFailed = 605003
    Error while sending email verification code, you may try again or contact support if this fails repetitively.

  • RetrevingEmailNotificationTemplateByNameFailed = 605004
    Error while sending email verification code, you may try again or contact support if this fails repetitively.

  • RegisterNotificationFailed = 605005
    Error while Adding/updating email notification, you may try again or contact support if this fails repetitively.

  • DeleteNotificationFailed = 605006
    Error while deleting email notification, you may try again or contact support if this fails repetitively.

  • UnsupportedLanguageInEmailTemplate = 605007
    Language used in Email notification template is not supported.

Feedback Controller (606000-606999)

  • A null InvalidFeedbackDTO was provided.
    InvalidFeedbackDTO = 606000

  • Adding a new feedback survey failed.
    AddFeedbackFailed = 606001

  • Get feedback by service id failed.
    GetFeedbackFailed = 606002

  • Get feedback count by service id failed.
    GetFeedbackByCountFailed = 606003

File Attachments Controller (607000-607999)

  • Md5HashNotMatching = 607000
    MD5 hash does not match.

  • FileNameWithUnsupportedCharacters = 607001
    File name consists unsupported characters.

  • VirusScanResultBlocked = 607002
    Virus Scan Result - Blocked.

Invoices Controller (608000-608999)

  • A null InvoiceDTO was provided.
    InvalidInvoice = 609000

  • Invoice creation failed.
    CreateInvoiceFailed = 609001

  • Invoice id is zero.
    InvoiceIdIsZero = 609002

  • Invoice update failed.
    UpdateInvoiceFailed = 609003

  • Invalid number reference, or both number provided at the same time.
    InvalidNumberOrReference = 609004

  • Invoice(s) not found.
    InvoiceNotFound = 609005

Metadata Definitions Controller (609000-609999)

Note: Not implemented yet.

  • CannotCreateStructure = 609000

Organization Controller (611000-611999)

  • Retrieving organization failed
    RetrievingOrganizationFailed = 611001

  • Organization Id is not valid
    InvalidOrganization = 611002

  • Adding organization failed

AddingOrganizationFailed = 611003

  • Updating organization failed
    UpdatingOrganizationFailed = 611004

  • Invalid argument
    InvalidArgument = 611005

  • Deleting organization failed
    DeletingOrganizationFailed = 611006

Notices Controller (612000-612999)

  • At least one service must be provided.
    Minimum1ServiceRequired = 612001

  • Notice with a certain id is not found.
    NoticeNotFound = 612002

  • Unable to get all notices.
    GetNoticesFailed = 612003

  • Adding a new notice failed.
    AddNoticeFailed = 612004

  • Updating a notice failed.
    UpdateNoticeFailed = 612005

  • Delete notice failed.
    DeleteNoticeFailed = 612006

  • Notice object is null.
    NoticeIsNull = 612007

  • Unable to get all notice types.
    GetNoticeTypesFailed = 612008

  • The start date should be before the end date.
    NoticeStartDateShouldBeBeforeEndDate = 612009

  • The display date should be before the end date.
    NoticeDisplayDateShouldBeBeforeEndDate = 612010

  • Only one service has to be selected for WarningNotice or InformationNotice.
    NoticeOneServiceShouldSelectedBeForWarningOrInfo = 612011

  • Header and Body are required for WarningNotice or InformationNotice.
    NoticeHeaderBodyRequired = 612012

  • Notice header for WarningNotice or InformationNotice should be less than the maximum character limit (150 characters).
    NoticeHeaderOverMaxCharacterLimit = 612013

  • Notice body for WarningNotice or InformationNotice should be less than the maximum character limit (500 characters).

    NoticeBodyOverMaxCharacterLimit = 612014

  • Header and Body shouldn't be entered for planned or unplanned outage.
    NoticeHeaderBodyShouldBeNullForOutageNotice = 612015

Permissions Controller (613000-613999)

  • RetrievingAllPermissionsFailed = 613001

Retrieving all permissions failed

  • RetrievingUserByPermissionsFailed = 613002

Get User by permissions failed

Portal Capabilities Controller (614000-614999)

  • Get portal capabilities failed.
    GetPortalCapabilitiesFailed = 614000

Service Preferences Controller (615000-615999)

  • RetrievingServicePreferenceFailed = 615001

  Retrieving service preferences failed

  • CreateOrUpdateServicePreferenceFailed = 615002

Create or Update service preference failed

  • DeletingServicePreferenceFailed = 615003

Deleting service preference failed

  • InvalidServicePreferenceFailed = 615004

Invalid service preference

Service Regulated Entities Controller (616000-616999)

  •  InvalidRegulatedEntityType = 616001
    Invalid regulated entity type.

  • RetrievingRegulatedEntityFailed = 616002
    Retrieving regulated entity failed.

  • AddRegulatedEntityFailed = 616003
    Add regulated entity failed.

  • UpdateRegulatedEntityFailed = 616004
    Update regulated entity failed.

Service Requests Controller (617000-617999)

  • RetrievingServiceRequestFailed = 617001
    Retrieving service request has failed.

  • RetrievingServiceRequestsByServicesFailed = 617002
    Retrieving service requests by services has failed.

  • RetrievingServiceRequestStatusesFailed = 617003
    Retrieving service request statuses has failed.

  • RetrievingServiceRequestStatusHistoryFailed = 617004
    Retrieving service request status history has failed.

  • RetrievingServiceArtifactsFailed = 617005
    Retrieving service request artifacts has failed.

  • AddServiceRequestFailed = 617006
    Add service request has failed.

  • ServiceRequestsQueryFailed = 617007
    Service request query has failed.

  • UpdateServiceRequestFailed = 617008
    Service Request couldn't be updated.

  • ServiceRequestsByServiceFailed = 617009
    Retrieving service requests by service has failed.

  • UpdateServiceRequestStatusFailed = 617010
    Service Request status couldn't be updated.

  • DeleteServiceRequestFailed = 617011
    Service Request couldn't be deleted.

  • InitiateTransferFailed = 617012
    Service Request couldn't be initiated.

  • CompleteTransferFailed = 617013
    Service Request couldn't be completed.

  • FileAttachmentByServiceRequestFailed = 617014
    Retrieving file attachment by service request has failed.

  • NoRequesterId = 617015
    Retrieving file attachment by service request has failed.

  • NoRequesterDetails = 617016
    Retrieving file attachment by service request has failed.

  • RetrievingUserAssignmentsFailed = 617017
    Retrieving user assignments has failed.

  • RetrievingStatusHistoryExFailed = 617018
    Retrieving extended status history has failed.

  • RetrievingStatusHistoryExByGuidFailed = 617019
    Retrieving extended status history by guid has failed.

  • UpdateDateCannotBeInFuture = 617020
    Update date cannot be in future.

  • ServiceRequestStatusLogNotFound = 617021
    Service Request status log not Found.

  • UpdateDateShouldBeAfterPreviousDate = 617022
    The update date should be greater than the previous date.

  • UpdateDateShouldBeBeforeNewerDate = 617023
    The update date should be less than the newer date.

  • UpdateDateShouldBeAfterPreviousDateAndBeforeNewerDate = 617024
    The update date should be greater than the previous date and less than the newer date.

  • UpdateStatusHistoryFailed = 617025
    Service Request Status couldn't be updated.

  • UserAssignmentExists = 617026
    User Assignment already exist.

  • AddUserAssignmentFailed = 617027
    User Assignments couldn't be added.

  • RemoveUserAssignmentFailed = 617028
    User Assignments couldn't be removed.

  • InvalidServiceStandard = 617029
    ServiceStandardId is not valid for the service.

  • InvalidServiceId = 617030
    Changing ServiceId not allowed.

  • DeletedStatus= 617031
    Changing ServiceId not allowed.

  • UpdateServiceRequestFail = 617032
    Update ServiceRequest failed.

  • RetrievingAuditHistoryFailed = 617033
    Retrieving audit history has failed.

  • InvalidServiceRequestId = 6170034
    Invalid ServiceRequest Id.

  • InvalidServiceRequestRevisedCreatedDate = 617035
    The Specified Revised Created Date is invalid.

  • ServiceRequestIdIsZero = 617036
    Service Request Id is zero.

  • AddMultipleUserAssignmentsFailed = 617037
    Multiple User Assignments couldn't be added.

  • RemoveMultipleUserAssignmentsFailed = 617038
    Multiple User Assignments couldn't be removed.

  • FilterByMetadataFailed = 617039
    Filter service request by metadata has failed.

Services Controller (618000-618999)

  • InvalidDatetime = 618001

future deactivation dateTime should be greater than the current dateTime

  • EnrollmentDeactivationFailed = 618002

Enrollment deactivation fails

  • RetrievingServiceInformationFailed = 618004

Retrieving service information failed

  • RetrievingActivitiesFailed = 618005

Retrieving activities failed

  • EnrollUserInServiceFailed = 618006

Enroll User In Service Failed

  • WithdrawUserFromServiceFailed = 618007

Withdraw User from a service Failed

  • ActivateUserInServiceFailed = 618008

Activate User in a Service Failed

  • DeactivateUserFromServiceFailed = 618009

Deactivate User from a Service Failed

  • InvalidReturnUrl = 618010

Return url Failed

  • InitiateInviteFailed = 618011

Initiate invite Failed

  • CompleteInviteWithInvalidArgumentFailed = 618012

Complete invite with invalid argument Failed

  • InviteWithInternalUserFailed = 618013

Invite with internal user failed

  • RetrievingUserFailed = 618014

Retrieving user failed

  • RetrievingNoticesByServiceFailed = 618015

Retrieving notices by service failed

  • RetrievingServicePermissionFailed = 618016

Retrieving service permissions failed

  • AddingServicePermissionFailed = 618017

Adding service permission failed

  • UpdateServicePermissionFailed = 618018

Update service permission failed

  • DeleteServicePermissionFailed = 618019

Delete service permissions failed

  • RetrievingServiceRegulatedEntityFailed = 618020

Retrieve the list of service regulated entities failed

  • RetrievingServiceCatalogFailed = 618021

Retrieving all services failed

Service Settings Controller (619000-619999)

  •  RetrievingServiceSettingFailed = 619001

Retrieving service setting failed

  • DeletingServiceSettingFailed = 619002

Deleting service setting failed

  • CreateOrUpdateServiceSettingFailed = 619003

Create or Update service setting failed

Users Controller (620000-620999)

  • Call to check whether user exists or not has failed
    UserExistsFailed = 620001

  • Call to check whether user exists or not has failed
    UserExistsFailed = 620001

  • Associate internal user to organization failed
    AssociateInternalUserToOrganizationFails = 620003

  • Retrieving users has failed
    RetrievingUsersFailed = 62000

  • Retrieving user using id has failed
    RetrievingUserByIdFailed = 620005

  • Retrieving user using PKI has failed
    RetrievingUserByPkiFailed = 620006

  • Retrieving users using email has failed
    RetrievingUsersByEmailFailed = 620007

  • Retrieving user using passed credentials has failed
    RetrievingUserByAuthInfoFailed = 620008

  • Retrieving request for user has failed
    RetrievingRequestsForUserFailed = 620009

  • Adding or updating user information has failed
    AddingOrUpdatingUserFailed = 620010

  • Deleting user has failed
    DeletingUserFailed = 620011

  • Retrieving organizations information for a user has failed
    RetrievingOrganizationsForUserFailed = 620012

  • Retrieving business systems information for a user has failed
    RetrievingBusinessSystemsForUserFailed = 620013

  • Retrieving services for a user has failed
    RetrievingServicesByUserFailed = 620014

  • Adding permission to service has failed
    AddingPermissionToServiceFailed = 620015

  • Deleting service permission has failed
    DeletingServicePermissionFailed = 620016

  • Retrieving notices for a user has failed
    RetrievingNoticesForUserFailed = 620017

  • Retrieving permissions of a user has failed
    RetrievingPermissionsByUserFailed = 620018

  • Retrieving permissions for a user's service has failed
    RetrievingPermissionsByUserAndServiceFailed = 620019

  • Searching users has failed
    UserSearchFailed = 620019

  • Retrieving granted applications by user id has failed.
    RetrievingExpiredNoticesForUserFailed = 620020

  • Adding Or Updating User Failed Because Email Already Taken
    AddingOrUpdatingUserFailedBecauseEmailAlreadyTaken = 620021

  • Retrieving granted applications by user id has failed.
    GetApplicationsFailed = 620022

  • Retrieving granted applications by user id has failed because of an invalid role id.

    GetApplicationsFailedByInvalidRoleId = 620023

Virus Scan Controller (621000-621999)

  •  

UserApplicationManagement Controller (623000 - 623999)

Note: This only for MTOA Platform team

  • Get application information with roles failed.
    GetApplicationByAppIdFailed = 623000

  • Get application information with roles and permission failed.
    ApplicationNotFound = 623001

  • Enroll user in application failed.
    EnrollUserInApplicationFailed = 623002

  • Manage account of this application is not enabled.
    ManageAccountNotEnabled = 623003

  • Unable to enroll the user in the application role.
    User has already the application role.
    UserHasApplicationRole = 623004

  • The Role is not currently supported for the application role enrollment.
    ApplicationRoleNotSupported = 623005

  • User cannot have more than one role per application (other than role 1 or 2).
    CannotNotHaveMoreThanOneAppRole = 623006

  • CreatedByUser does not have the role to manage the application user account.
    MustHaveRoleToManageUser = 623007

  • Get users by application id failed
    GetUsersByApplicationIdFailed = 620338