#Error codes

This guide documents all error codes returned by the Setu Insights API. Understanding these codes will help you handle errors gracefully and debug integration issues effectively.

#Error response structure

All API v3 error responses follow a consistent structure:

{
  "timestamp": "2023-05-16T09:23:39.115Z",
  "version": "0.73.1",
  "txnid": "txn_12345",
  "error": {
    "code": "api_template_not_found",
    "type": "validation",
    "message": "Template with id tpl_123 not found",
    "details": {
      "template_id": "tpl_123",
      "http_status": 404,
      "param": "templateId"
    }
  }
}

The error object contains:

• code—Unique identifier for programmatic error handling
• type—Error category (validation, auth, internal, etc.)
• message—Human-readable description
• details—Additional context including the parameter causing the error

#Error codes reference

All possible error codes that we support:

#Error types

Errors are categorized into the following types:

#API Error Codes

#Template Management

#GET /v3/template

#POST /v3/template

#Data Ingestion

#POST /v3/fiData

#Insight Generation

#POST /v3/insight

#GET /v3/insight

#Data Purging

#DELETE /v3/purge

#Authentication & Authorization

#Rate Limiting

#Generic Validation Errors

These errors occur when request validation fails at the API level.

#Example validation error response

{
  "timestamp": "2023-05-16T09:23:39.115Z",
  "version": "0.73.1",
  "txnid": "txn_12345",
  "error": {
    "code": "api_validation_error",
    "type": "validation",
    "message": "Request validation failed",
    "details": {
      "total_errors": 2,
      "error_message": [
        "field required -> templateId",
        "ensure this value has at least 1 characters -> refId"
      ]
    }
  }
}

#Insight Processing Errors

These errors occur during insight computation and are returned within successful API responses (2xx status) but with status: "error" for affected insights.

#Example insight error response

{
  "status": "Success",
  "body": {
    "accounts": [
      {
        "accountIdentifierKey": "acc_123",
        "insights": [
          {
            "indicatorName": "salary_analysis",
            "status": "error",
            "error": {
              "code": "ins_insufficient_history",
              "type": "insight",
              "message": "Insufficient transaction history for salary analysis",
              "details": {
                "required_months": 6,
                "available_months": 2
              }
            }
          }
        ]
      }
    ]
  }
}

#System Errors

#Example internal server error response

{
  "timestamp": "2023-05-16T09:23:39.115Z",
  "version": "0.73.1",
  "txnid": "txn_12345",
  "error": {
    "code": "internal_error",
    "type": "internal",
    "message": "Internal Server Error",
    "details": {
      "exception_type": "ServiceConnectionError"
    }
  }
}

#Best Practices

1. Programmatic handling—Always check the error code rather than parsing error messages for conditional logic
2. User experience—Display the human-readable message to end users
3. Debugging—Use the details object for additional context during troubleshooting
4. Retry logic—Implement appropriate retry mechanisms for temporary errors (rate limits, upstream errors)
5. Monitoring—Track error rates by code to identify systematic issues

#HTTP Status Code Reference

• 400 Bad Request—Business logic errors, specific validation failures
• 401 Unauthorized—Missing or invalid authentication
• 403 Forbidden—Insufficient permissions
• 404 Not Found—Resource doesn't exist
• 422 Unprocessable Entity—Request validation failed (malformed requests)
• 429 Too Many Requests—Rate limit exceeded
• 500 Internal Server Error—Unexpected server errors
• 502/503 Service Unavailable—Upstream service issues