Overview

The Platform APIs indicate the success or failure of an API request with an HTTP response status code.

An HTTP response status code is a standard response sent from a server to a client that indicates whether a specific request was successfully completed. These HTTP response status codes are displayed in the message body of the HTTP response.

The Intelligent Risk Platform uses standard HTTP response codes to indicate the success or failure of an API request. HTTP response status codes enable you to verify normal behavior and provide context for understanding exceptions. This page summarizes the significance of these response codes and links to documentation in RFC 9110.

200 OK

An 200 OK HTTP response status code indicates that the request was successful.

The Platform APIs generally return a 200 OK response for all successful GET requests.

201 Created

The 201 Created HTTP response status code indicates that the request has been accepted or fulfilled, and that one or more new API resources has been created.

202 Accepted

The 202 Accepted HTTP response status code indicates that the request has been accepted for processing, and that the the Intelligent Risk Platform ahs created a job to process the request.

Intelligent Risk Platform generally returns a 202 Accepted response when it adds a new job to the workflow engine queue.

204 No Content

The 204 No Content HTTP response status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response content. Metadata in the response header fields refer to the target API resource and its selected representation after the requested action was applied.

The Intelligent Risk Platform often returns a 204 No Content response for successful DELETE or PATCH requests. These operations do not create jobs and do not return data in the response body.

400 Bad Request

The 400 Bad Request HTTP response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

Indicates a validation error or that the request parameters were missing or incorrect. For example, if the request omits a required x-rms-resource-group-id parameter.

A 400 Bad Request response passes a custom error in the response body that provides details about the cause of the error. To learn more about Intelligent Risk Platform custom errors, see Custom Error Codes.

{
  "code": "INT-999",
  "message": "The resource ID is not specified.",
  "logId": "e5c4187b4deee9c09"
}

This error is returned if parameter value specified in the request is not valid:

{
  "message": "Validation failed. Please check your request.",
  "validationErrors": [
    {
      "field": "Include",
      "message": "The value 'role' is not valid."
    }
  ]
}

401 Unauthorized

The 401 Unauthorized HTTP response status code indicates that the credentials are missing or invalid.

This error is frequently returned if the client is unauthorized to access the API resource or lacks permission to perform an operation.

The Intelligent Risk Platform uses access rights and role-based access controls to restrict access to resources. Both access rights and permissions are granted to principals based on group membership. To learn more, see User Groups.

The response body may return the reason that the client was denied access to the API resource, e.g the client did not pass an API key or if the API key does not belong to a user group that is authorized to access the API resource.

{
  "message": "Unauthorized"
}

403 Forbidden

The 403 Forbidden HTTP response status code indicates that Cannot access: Access Control, Licensing or Rate Limiting.

A 403 Forbidden response passes a custom error in the response body that provides details about the cause of the error. To learn more about Intelligent Risk Platform custom errors, see Custom Error Codes.

404 Not Found

The 404 Not Found HTTP response status code indicates that the server cannot find the target API resource.

A 404 Not Found response often returns an error messsage in the body of the response:

{
  "message": "Unable to find group 'efe1c0bd-2640-42ce-8c60-b499db77a15a'."
}

405 Method Not Allowed

The 405 Method Not Allowed HTTP response status code indicates that the client is not authorized to make the request. For more information, see Access Control

422 Unprocessable Content

The 422 Unprocessable Content HTTP response status code indicates that the server understands the content type of the request, and that the syntax of the requestis correct, but that the server was unable to process request.

This response may be returned when parameter values specified in the request are of the wrong data type. For example, the parameter may require an array of strings.

429 Too Many Requests

The 429 Too Many Requests HTTP response status code indicates the principal has sent too many requests within a given amount of time ("rate limiting").

A rate limit is an mechanism that restricts the number of API requests that a client can make within a specific time period. The Intelligence Risk Platform limits the number of API requests that a client can make to 2000 requests per second. This restriction is designed to prevent denial of service attacks and ensure that all clients can access and utilize Intelligent Risk Platform API resources.

Platform API clients most often see the 429 Too Many Requests HTTP response status code in workflows that require them to poll an endpoint for the status of a job. To learn more see Polling Job Status.

500 Internal Server Error

The 500 Internal Server Error HTTP response status code indicates that the server could not fulfill the request due to an unexpected condition.