Risk Cloud API: Troubleshooting

Use the Risk Cloud® API Troubleshooting Guide to identify and resolve common issues that can occur when building or maintaining your custom API integrations with Risk Cloud.

Make your integrations more reliable and easier to maintain by understanding how to interpret API errors and fix them quickly. This guide walks through typical problems users encounter when working with the Risk Cloud API—like authentication issues, malformed requests, or unexpected status codes—and provides actionable steps to debug them.

The most common issues include:

• 401 Unauthorized – usually caused by incorrect or missing credentials
• 400 Bad Request – often due to improperly formatted JSON or missing required fields
• 403 Forbidden – can occur if the API token lacks the correct permissions
• 404 Not Found – typically means an incorrect endpoint or resource ID was used

To resolve most API issues, follow these steps:

1. Verify Authentication Method
   Ensure you’re using the correct token type and header format for the endpoint.
2. Check Endpoint and Payload
   Confirm the endpoint URL and request body match the expected structure from the API documentation.
3. Read the Error Message
   Review the returned status code and error message—they often indicate the root cause.
4. Confirm Permissions
   Make sure your API token or user role has the required permissions for the action.

This guide includes code examples, best practices, and quick tips to help you move past issues faster and keep your integrations running smoothly.

401 Unauthorized Errors

A 401 Unauthorized error means your API request is not properly authenticated—the Risk Cloud API could not verify your credentials.

This usually happens when:

Your Client ID and Client Secret are missing, incorrect, or improperly encoded

You’re sending the wrong type of authorization header for the endpoint

You’re using an incorrect or expired API Access Token

Resolution Steps

1. Check the Type of Authentication Required
   • For the POST /api/v1/account/token endpoint:
     • Use Authorization: Basic {ENCODED_BASE64_STRING}
     • This does not require a bearer token
     • The {ENCODED_BASE64_STRING} is a Base64-encoded string of your Client ID and Client Secret
2. Generate a New Bearer Token
   • If you’re trying to access any other endpoint (like /v2/applications), you’ll need a valid Bearer token
   • After calling POST /api/v1/account/token, use the returned access token in your requests: cssCopyEditAuthorization: Bearer {YOUR_ACCESS_TOKEN}
3. Reset or Double-Check Credentials
   • If issues persist, try resetting your Client Secret or verify with your admin that your credentials are correct

403 Forbidden Errors

A 403 Forbidden error means that your API request was authenticated, but your API token does not have permission to access the resource you’re requesting.

This typically happens when:

You are using a token created for a user with restricted access

Your API user does not have the correct Application permissions in Risk Cloud

You are trying to access data or endpoints outside the scope of your assigned roles or step permissions

Resolution Steps

1. Verify Application Access
   • Ensure the user tied to your API token has permission to view or modify the application, workflow, or records you’re trying to access.
   • If accessing data from a specific step or field, verify that the user has access to that part of the workflow.
2. Check User Roles and Permissions
   • Review the user’s assigned roles and what access those roles provide.
   • You may need to contact your Risk Cloud admin to confirm the correct roles are assigned.
3. Try the Request in the UI
   • If you’re unsure whether access is the issue, try viewing or interacting with the resource in the Risk Cloud UI as the same user. If it’s blocked there too, it’s definitely a permission issue.

For more help getting started with Risk Cloud API, check out our Getting Started guide or contact your customer success manager.