Web Service Error Messages

  • Web Services
  • UMPI

Unsuccessful Universal MPI web service requests will return typical 400/500 HTTP status codes for client or server errors, depending on the situation. Examples could include common status codes such as 401 (Unauthorized), 404 (Not Found), 500 (Internal Service Error), 503 (Service Unavailable) or 504 (Gateway Timeout).

In all cases, if the web service succeeded to the point where JSON content was returned in the web service response, the success Boolean will be false.

Web Service Execution Messages - General Errors

The following table describes web service response messages for more general, varied, and uncommon errors. These outcomes are possible with any web service.

Scenario

HTTP

Status

Message String

Client submits a web service request from an IP address that is not added to the allow list by Verato

404 or

504

Service request will not make it to the Verato application tier, so you will get an HTTP message back that may contain "server connection refused", "timeout", or "socket connection reset by peer".

Client submits a web service request with a missing or invalid certificate.

0

Service request will not make it to the Verato application tier, so you may get a response that may contain "Error getting response;

java.net.ssl.SSLHandshakeException: Received fatal alert: bad_certificate"

Client submits a web service request with incorrect username and/or password.

401

Service request makes it to the Verato application tier but fails, so the Verato standard web service response will not be provided.

Instead, there will be an HTTP response that contains a title of "HTTP Status 401 – Unauthorized", and the body of the message will include text along the lines of "User is not authenticated"

Client submits a web service request to a base URL that is incorrect or does not exist. In the example provided, the base

url provided was https://bad.url.verato.com.

0

Service request will not make it to the Verato application tier, so you will get some kind of response that may look like "Error getting response; java.net.UnknownHostException: bad.url.verato.com"

Client submits a volume of web service requests that exceeds defined limits. Any requests beyond the defined limit are not processed. For example, if UMPI is configured to limit requests at 25 transaction per second, the 26th and beyond transactions received within 1 second would trigger this response.

429

Requests are being sent at a rate above the defined limit. Please reduce the rate and retry your requests.

Client submits a web service request to the correct base URL but with an invalid or misspelled resource endpoint. In the example provided, the client provided the resource name of “pasteIdentity” instead of “postIdentity”.

200

configuration.error | No microservice configuration found for pasteIdentity.default

Client submits a web service request with invalid or incomplete JSON that does not contain the expected fields based on the requested web service. This happens most often when a client passes into the request a JSON object that was intended for a different type of web service. In the example provided, the client passed in the JSON object suitable for a “demographicsQuery” request into the “nativeIdQuery” web service. The “nativeIdQuery” web service did not find the first field it was expecting in the JSON, which is the “source” field.

200

missing.request.field | The request was missing a value for field source.

Client submits a web service request where the JSON includes an unhandled non-ascii or extended ascii character. Typically the Universal MPI is expecting English characters from the ascii character set. Error handling is built in to handle certain extended ascii characters, but non-ascii characters or some extended ascii characters may not be handled, resulting in a failure.

200

The content of the “message” string will vary slightly depending on the web service, but generally it will contain the string “500 null”. The example below is from a failed postIdentity request: operation.failed | Requested operation failed with following error : PostIdentityService failure: 500 null ( Collected values at time of exception: url=http://internal-elb- app-demo-link-699819618.us-east- 1.elb.amazonaws.com:8080/link-core/svc/postIdentityService/default )

One sub-step within the overall web service operation failed due to a server capacity error within Verato’s infrastructure.

200

operation.failed | Requested operation failed with following error : PostIdentityService failure: 503 Service Unavailable: Back-end server is at capacity ( Collected values at time of exception: url=http://internal-elb-app-cust0013- test-443119918.us-east- 1.elb.amazonaws.com:8080/link-core/svc/postIdentityService/default )

One sub-step within the overall web service operation failed due to a timeout within Verato’s infrastructure.

200

operation.failed | Requested operation failed with following error : PostIdentityService failure: 504 GATEWAY_TIMEOUT ( Collected values at time of exception: url=http://internal-elb-app-cust0022- 602572535.us-east-1.elb.amazonaws.com:8080/link-core/svc/postIdentityService/default )

Web service execution messages - other error messages 

The following table describes the message string in the web service response when the web service completes with an atypical or unusual outcome. In these scenarios:

  • The web service completed
  • The HTTP status code will be 200
  • The success Boolean will be set to false in the web service response because the outcome was not completely successful.

Web service

Scenario

Message String

postIdentity

Overlay error – the demographic data posted is very different from the current demographics for the same Source + Native ID, indicating an overlay condition. The identity is not updated in Universal MPI.

operation.failed | Requested operation failed with following error : PostIdentityService failure: PostIdentityRequest failed. Cause : IngestionService failure: Error ingesting

entity: Overlay Error Detected

postIdentity

The requesting user attempted to post an identity with a Source for which the user does not have permissions to update. In this example, the user attempted to post an identity from

source=verato.source.e.

unauthorized.request | The client is not authorized for the requested operation: no write permissions on source: verato.source.e

postIdentity

Race condition failure – multiple concurrent web service requests were made to update the same Source + Native ID at the same time. One of the requests succeeded, and the other request failed – the application uses version control to ensure that data is not corrupted by two concurrent requests. The request that failed returns this

message.

operation.failed | Requested operation failed with following error : PostIdentityService failure: PostIdentityRequest failed. Cause : IngestionService failure: Zero rows updated when storing identity: 5bdc88ab2b3a2c6e1000e014 ver: 19118. Possible attempt to store stale object

postIdentity

The requesting user attempted to post an identity for a Source + Native ID that is in a merged/retired state. This would only happen if the Source + Native ID was previously merged using the mergeIdentity web service. Once a Source + Native ID has been merged, it can no longer be updated. It must be unmerged before it can be updated.

operation.failed | Requested operation failed with following error : PostIdentityService failure: PostIdentityRequest failed. Cause : IngestionService failure: Error ingesting entity: source+nativeId already in the retired state and cannot be updated

postIdentity

The postIdentity request object includes more than one Source + Native ID value (even if it’s just the same Source + Native ID value repeated twice). A request with more than one Source + Native ID in

the request object will fail.

invalid.request | The request was invalid: only 1 source may be specified when posting an Identity

nativeIdQuery

The requesting user attempted to retrieve an identity from a Source for which the user does not have

read permissions. Regardless of

unauthorized.request | The client is not authorized for the requested operation: no

 

whether the identity actually exists in Universal MPI or not, this message is returned. In this example, the user attempted to retrieve an identity from

source=verato.source.e.

read permissions on source: verato.source.e

identityIdQuery

The requested Link ID is not a 24- character hexadecimal string.

operation.failed | Requested operation failed with following error :

identity.query

deleteSourceIdentity

The requesting user attempted to delete a record from a Source for which the user does not have write permissions. In this example, the user attempted to retrieve an identity from

source=verato.source.e.

unauthorized.request | The client is not authorized for the requested operation: insufficent access permissions for source: verato.source.e

linkIdentities

The linkIdentities request was invalid because the specified Source + Native ID values already exist in the same Link ID – they are already linked. In this example, the request to link source=verato.source.a and nativeId=TEST101 with source=verato.source.a and

nativeId=TEST102 was invalid.

dupe.request.ignored | Request was previously processed.

Additional info: verato.source.a:TEST102 already linked to verato.source.a:TEST101

linkIdentities

The linkIdentities request was invalid because one or both of the requested Source + Native ID values does not exist in Universal MPI. In this example, the invalid Source + Native ID was verato.source.a + TEST103.

missing.required.record | Record not found : verato.source.a:TEST103

linkIdentities

The requesting user attempted to link records from a Source for which the user does not have write permissions. In this example, the user attempted to link a record from

source=verato.source.e.

unauthorized.request | The client is not authorized for the requested operation: insufficient access permissions for source: verato.source.e

linkIdentities

The requesting user attempted to link a Source + Native ID that is in a merged/retired state. This would only happen if the Source + Native ID was previously merged using the mergeIdentity web service. Once a Source + Native ID has been merged, it can no longer be updated.

It must be unmerged first.

One or more source:nativeId combinations are in retired state

unlinkIdentities

The unlinkIdentities request was invalid because the specified Source

+ Native ID values already exist in different Link IDs.

no.action.taken | Explanation

: The source+nativeID combinations are already in separate entities

unlinkIdentities

The unlinkIdentities request was invalid because one or both of the requested Source + Native ID values does not exist in Universal MPI.

no.action.taken | Explanation

: One or more source:nativeId combinations not in Link DB

unlinkIdentities

The requesting user attempted to unlink records from a Source for which the user does not have write permissions. In this example, the user attempted to unlink a record

from source=verato.source.e.

unauthorized.request | The client is not authorized for the requested operation: insufficent access permissions for source: verato.source.e

unlinkIdentities

The requesting user attempted to unlink a Source + Native ID that is in a merged/retired state. This would only happen if the Source + Native ID was previously merged using the mergeIdentity web service. Once a Source + Native ID has been merged, it can no longer be updated. It must be unmerged first.

One or more source:nativeId combinations are in retired state

mergeIdentities

The mergeIdentities request was invalid because the specified Source + Native ID to be merged is already in the merged state.

The toRetire source+nativeID is already in the retired/merged away state

mergeIdentities

The mergeIdentities request was invalid because one or both of the requested Source + Native ID values does not exist in Universal MPI.

One or more source:nativeId combinations not in Link DB

mergeIdentities

The requesting user attempted to merge records from a Source for which the user does not have write permissions. In this example, the user attempted to merge a record

from source=verato.source.e.

unauthorized.request | The client is not authorized for the requested operation: insufficient access permissions for source: verato.source.e

unmergeIdentities

The unmergeIdentities request was invalid because the specified Source + Native ID value already exist in the unmerged/active state.

The unmerge source+nativeID is already in the active/unmerged state

unmergeIdentities

The unmergeIdentities request was invalid because one or both of the requested Source + Native ID values does not exist in Universal MPI.

One or more source:nativeId combinations not in Link DB

unmergeIdentities

The requesting user attempted to unmerge records from a Source for which the user does not have write permissions. In this example, the user attempted to unmerge a record from source=verato.source.e.

unauthorized.request | The client is not authorized for the requested operation: insufficient access permissions for source: verato.source.e

searchNotifications

The searchNotifications request was invalid because the start date was later than the end date.

"EndDate cannot be earlier than the startDate"

searchNotifications

The searchNotifications request was invalid because the page number was <0.

"Page number cannot be less than 0"

searchNotifications

The searchNotifications request was invalid because the page size was <1 or >100.

"Page size must be greater than 0"

or

Page size cannot be greater

than 100"