Error Codes & Troubleshooting Guide

Complete reference for Deepvue API error codes and HTTP status codes. Learn how to handle common errors and debug your integration quickly.

{
  "detail": "Inactive client_id"
}

Overview

Deepvue APIs return standard HTTP status codes to indicate the success or failure of requests. Error responses include a detail field with a human-readable message describing the issue.

HTTP status codes

Status Code	Meaning	Description
`200`	OK	Request completed successfully
`400`	Bad Request	Invalid request parameters or inactive client
`401`	Unauthorized	Authentication failed or missing credentials
`403`	Forbidden	Valid credentials but insufficient access
`422`	Validation Error	Request parameters failed validation
`429`	Too Many Requests	Rate limit exceeded — slow down and retry
`500`	Internal Server Error	Server-side issue — retry or contact support
`503`	Service Unavailable	Upstream data source is temporarily unavailable

Error response format

Error responses include a detail field explaining the issue:

Common errors and solutions

Your client_id is inactive, disabled, or the request is malformed.

Common messages: "Inactive client_id", "Bad Request"

Verify your credentials in the Deepvue Dashboard
Check if your account is active and in good standing
Ensure the request body and query parameters are correctly formatted
Contact support if the issue persists

The request is missing valid authentication credentials or the provided credentials are invalid.

Common messages: "Not authenticated", "Could not validate credentials", "Invalid client_id", "Invalid client_id or client_secret, access Denied", "Authorization failure", "Incorrect client_id or client_secret"

Include the Authorization: Bearer YOUR_ACCESS_TOKEN header
Include the x-api-key: YOUR_CLIENT_SECRET header
Verify your client_id and client_secret are correct and match your environment
Ensure your access token has not expired (tokens are valid for 24 hours)
Generate a new token via the Authorize endpoint

Your access token is invalid, expired, or you do not have permission to access the requested resource.

Common messages: "Not a valid token", "Access forbidden"

Generate a new token via POST /v1/authorize
Verify that you are using the correct client_secret as the x-api-key header
Ensure your account has access to the requested API product

You have exceeded the rate limit for your plan.

Pause requests and retry with exponential backoff
Spread requests evenly over time instead of sending bursts
Review your plan limits on the Rate Limits page
Contact support@deepvue.tech if you need higher limits

The request parameters failed validation.

Check the format of input parameters (e.g., PAN must match [A-Z]{5}[0-9]{4}[A-Z])
Ensure all required parameters are included
Review the API reference for the specific endpoint's parameter requirements

An unexpected error occurred on the server.

Common message: "Internal Server Error"

This is a transient error — retry the request with exponential backoff
If the error persists across multiple retries, contact support@deepvue.tech with the endpoint, request parameters, and timestamp
Check the API Status page for any ongoing incidents

The upstream data source is temporarily unavailable.

Common message: "Source Unavailable"

This is a transient error — retry the request after a short delay
The issue is typically with the upstream government or financial data source, not Deepvue
Check the API Status page for any ongoing incidents or contact support

Best practices

Always check the HTTP status code before parsing the response body
Implement retry logic with exponential backoff for 500 and 503 errors
Log the transaction_id from successful responses for debugging and support requests
Monitor your API usage through the dashboard's logging section
Handle token expiration gracefully by refreshing before the 24-hour window expires

Was this page helpful?

Last updated Mar 17, 2026