Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 39 Next »

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

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

  • InternalError = 901000 // instead of disclosing details, this error may be used

  • MtapiSettingError = 901001 // instead of disclosing details, this error may be used

  • ArgumentError = 901002, // use this status code for argument related errors where the app used to throw "ArgumentException", where error handler logs error however return a bad request to the caller

  • EnrollmentInServiceRequired = 901003 // use this status code if an operation cannot be performed because it requires users to be enrolled in a service

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)

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 = 604004

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)

  • InvalidServiceRequestId = 607000 Note: app uses ServiceRequestNotFound = 4041001

  • Md5HashNotMatching = 607000
    MD5 hash does not match.

  • FileNameWithUnsupportedCharacters = 607001
    File name consists unsupported characters.

  • VirusScanResultBlocked = 607002
    Virus Scan Result - Blocked.

  • InvalidVirusScanUrl = 607004 Note: app uses MtapiSettingError = 901001

  • MISSING_WORKFLOW_RULE = 7005 Note: app uses MtapiSettingError = 901001

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

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.

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)

Note: Not implemented yet.

  • InvalidUserId = 620000

  • InvalidUserType = 620001

Virus Scan Controller (621000-621999)

  • No labels