🚨Error Responses

💡 Comprehensive guide to error responses, validation, and troubleshooting

📊 Error Response Structure

All error responses follow a consistent envelope structure:

{
  "success": false,
  "message": "Human-readable error description",
  "data": {}
}

🏷️ Error Code Categories

HTTP Status Codes

Status Code

❌ Common Error Scenarios

1. Missing Required Fields (400)

What happened: Your request is missing required information

Response example:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "OrderId": [
      "This field is required"
    ],
    "Currency": [
      "This field is required"
    ]
  }
}

Suggested actions:

Review the errors object to identify missing fields
Ensure all required fields are included in your request
Check field names match exactly (case-sensitive)

2. Field Length Exceeded (400)

What happened: One or more fields exceed the maximum allowed length

Response example:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "CustomerId": [
      "Maximum length is 100 characters"
    ],
    "Language": [
      "Maximum length is 10 characters"
    ]
  }
}

Suggested actions:

Truncate field values to respect maximum lengths
Implement client-side validation before sending requests
Review field length limits in API documentation

3. Tenant Not Found (404)

What happened: The tenant ID you provided does not exist in our system

Response example:

{
  "success": false,
  "message": "Tenant not found.",
  "data": {}
}

Status code: 404 Not Found

Suggested actions:

Verify the tenant ID is correct (must be a valid GUID)
Ensure tenant is properly configured in the system
Check that you're using the correct environment (dev/staging/production)
Contact support if tenant should exist

4. Resource Not Found (404)

What happened: The resource you're trying to delete does not exist

Response examples:

{
  "success": false,
  "message": "Customer not found.",
  "data": {}
}

{
  "success": false,
  "message": "Order not found.",
  "data": {}
}

{
  "success": false,
  "message": "Product not found.",
  "data": {}
}

Suggested actions:

Verify the resource ID exists
Check if resource was already deleted
Ensure using correct identifier format

5. Storage/Delete Failure (500)

When it occurs: An error occurred while deleting a resource from storage

Response examples:

{
  "success": false,
  "message": "Failed to delete customer.",
  "data": {}
}

{
  "success": false,
  "message": "Failed to delete order.",
  "data": {}
}

{
  "success": false,
  "message": "Failed to delete product.",
  "data": {}
}

Suggested actions:

Retry the request with exponential backoff
Check system status for outages
Contact support if errors persist
Implement circuit breaker pattern for resilience

6. Internal Server Error (500)

When it occurs: An unexpected error occurred while processing your request

Response example:

{
  "success": false,
  "message": "An unexpected error occurred. Please try again.",
  "data": {}
}

Suggested actions:

Retry the request with exponential backoff
Check system status for outages
Contact support if errors persist
Implement circuit breaker pattern for resilience

6. Invalid Request Format (400)

What happened: Your request body is not properly formatted

Response example:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid JSON format"
}

Suggested actions:

Validate JSON syntax
Ensure Content-Type header is application/json
Check for proper array wrapping (endpoints expect arrays)

✅ How Request Validation Works

We automatically validate your API requests to ensure data quality and prevent errors.

What We Check

Required Information

All mandatory fields are present in your request
At least one identifier is provided (e.g., Email or CustomerId)

Data Integrity

Field values match expected data types (strings, numbers, booleans)
Text fields don't exceed maximum lengths
Dates are in valid ISO-8601 format

Business Rules

Currency codes follow ISO 4217 standard
Language tags follow IETF BCP 47 standard
Email addresses are properly formatted

When Validation Fails

If your request doesn't meet these requirements, you'll immediately receive a 400 Bad Request response with:

Specific field names that need correction
Clear description of what's wrong
Suggested fixes

Example validation error:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "OrderId": ["This field is required"],
    "Currency": ["Maximum length is 3 characters"]
  }
}

Best Practice

Validate data on your side before sending to avoid round-trip errors:

Check required fields are present
Verify string lengths
Ensure data types are correct

🔍 Validation Error Decoder

Quick reference to understand and fix common validation errors.

Understanding Error Field Paths

The errors object uses array notation to show exactly where the problem is:

Error Path

What It Means

[0].ProductId

First product in array is missing ProductId

[0].ProductVariants[0].Sku

First variant of first product is missing Sku

[2].OrderItems[1].Price

Second item in third order is missing Price

CustomerId

Single object (not array) missing CustomerId

Common Validation Errors & Fixes

Error Message

What It Means

How to Fix

"The ProductId field is required."

Missing required ProductId

Add "ProductId": "your-id" to product

"The Currency field is required."

Missing required Currency

Add "Currency": "USD" (or EUR, GBP, etc.)

"The field ProductId must be a string with a maximum length of 100."

ProductId too long

Shorten ID to 100 characters or less

"The field Currency must be a string with a maximum length of 3."

Currency too long

Use 3-letter ISO code: USD, EUR, GBP

"The Language field is required."

Missing required Language

Add "Language": "en-US" (IETF BCP 47 format)

"The GdprOptin field is required."

Missing required GdprOptin

Add "GdprOptin": true or false

Field Requirements by Endpoint

Products API

Required:

ProductId (string, max 100 chars)
ProductVariants (array, can be empty [])

Per Variant (if variants exist):

VariantId (string, max 100 chars)
Sku (string, max 50 chars)

Customers API

Required (depends on tenant config):

Either CustomerId OR Email (at least one)
Sometimes Language (check tenant settings)
Sometimes GdprOptin (check tenant settings)

Orders API

Required:

OrderId (string, max 100 chars)
Currency (string, max 3 chars, use 3-letter code)

Per Order Item:

ProductId (string, max 100 chars)
Sku (string, max 50 chars)
Quantity (integer)
Price (number)

Quick Fixes Checklist

Before making your API request:

All required fields are present
Field names are spelled correctly (case-sensitive!)
String lengths don't exceed limits
Arrays are properly formatted [{...}]
Currency uses 3-letter ISO code (USD, EUR, GBP)
Language uses IETF format (en-US, de-DE, fr-FR)
Boolean values are true/false, not strings
Dates are in ISO-8601 format: 2024-12-22T14:09:16Z

💡 Best Practices for Error Handling

Client-Side Implementation

// Example error handling with retry logic
async function callApiWithRetry(url, data, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-replenit-auth-key': 'YOUR_KEY'
        },
        body: JSON.stringify(data)
      });

      const result = await response.json();

      if (response.ok) {
        return result;
      }

      // Handle specific error codes
      if (response.status === 400) {
        console.error('Validation error:', result);
        throw new Error('Invalid request data');
      }

      if (response.status === 404) {
        console.error('Resource not found:', result);
        throw new Error('Resource does not exist');
      }

      // Retry on 500 errors
      if (response.status === 500 && attempt < maxRetries) {
        console.warn(`Attempt ${attempt} failed, retrying...`);
        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        continue;
      }

      throw new Error(result.message || 'API request failed');
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

Validation Before Submission

// Validate customer data before sending
function validateCustomer(customer) {
  const errors = [];
  
  // At least one identifier required
  if (!customer.CustomerId && !customer.Email) {
    errors.push('Either CustomerId or Email is required');
  }
  
  // Check maximum lengths
  const maxLengths = {
    CustomerId: 100,
    Email: 255,
    Name: 100,
    Surname: 300,
    Phone: 20,
    Language: 10,
    Username: 500
  };
  
  for (const [field, maxLength] of Object.entries(maxLengths)) {
    if (customer[field]?.length > maxLength) {
      errors.push(`${field} exceeds maximum length of ${maxLength}`);
    }
  }
  
  // Validate required fields
  if (customer.GdprOptin === undefined || customer.GdprOptin === null) {
    errors.push('GdprOptin is required');
  }
  
  return errors;
}

// Usage example
const validation = validateCustomer(myCustomer);
if (validation.length > 0) {
  console.error('Validation failed:', validation);
} else {
  // Safe to send
  await submitCustomer(myCustomer);
}

✅ Pre-Flight Validation

Catch errors BEFORE making API calls:

Customer Validation Script

def validate_customer_before_send(customer):
    """
    Validates customer data before API call.
    Returns list of errors (empty if valid).
    """
    errors = []
    
    # Required: At least one identifier
    if not customer.get('CustomerId') and not customer.get('Email'):
        errors.append("❌ Must include CustomerId or Email")
    
    # String length validation
    string_fields = {
        'CustomerId': 100,
        'Email': 255,
        'Name': 100,
        'Surname': 300,
        'Phone': 20,
        'Language': 10,
        'Username': 500
    }
    
    for field, max_len in string_fields.items():
        if customer.get(field) and len(customer[field]) > max_len:
            errors.append(f"❌ {field} too long: {len(customer[field])}/{max_len}")
    
    # Email format (basic check)
    if customer.get('Email') and '@' not in customer.get('Email', ''):
        errors.append("❌ Email format invalid")
    
    return errors

# Usage
customer = {
    "CustomerId": "C-001",
    "Email": "test@example.com",
    "Name": "Test"
}

validation_errors = validate_customer_before_send(customer)

if validation_errors:
    print("⚠️ Validation failed:")
    for error in validation_errors:
        print(f"  {error}")
else:
    print("✅ Customer is valid - safe to send")
    # Make API call here

Order Validation Script

def validate_order_before_send(order):
    """Validates order data before API call."""
    errors = []
    
    # Required fields
    if not order.get('OrderId'):
        errors.append("❌ OrderId is required")
    if not order.get('Currency'):
        errors.append("❌ Currency is required")
    
    # String length
    if order.get('OrderId') and len(order['OrderId']) > 100:
        errors.append(f"❌ OrderId too long: {len(order['OrderId'])}/100")
    if order.get('Currency') and len(order['Currency']) > 3:
        errors.append(f"❌ Currency too long: {len(order['Currency'])}/3")
    
    # Currency format (3 uppercase letters)
    import re
    if order.get('Currency') and not re.match(r'^[A-Z]{3}$', order['Currency']):
        errors.append("❌ Currency must be 3 uppercase letters (e.g., USD, EUR)")
    
    # Order items validation
    for idx, item in enumerate(order.get('OrderItems', [])):
        if not item.get('ProductId'):
            errors.append(f"❌ OrderItems[{idx}].ProductId is required")
        if not item.get('Sku'):
            errors.append(f"❌ OrderItems[{idx}].Sku is required")
        if not item.get('Quantity'):
            errors.append(f"❌ OrderItems[{idx}].Quantity is required")
        if not item.get('Price'):
            errors.append(f"❌ OrderItems[{idx}].Price is required")
    
    return errors

1. Check Request Headers

curl -v -X POST "https://api.replen.it/customers/{tenantId}" \
  -H "Content-Type: application/json" \
  -H "x-replenit-auth-key: YOUR_KEY" \
  -d '[{"CustomerId": "123"}]'

2. Validate JSON Structure

# Use jq to validate and format JSON
echo '[{"CustomerId": "123"}]' | jq .

3. Enable Detailed Logging

Check traceId in error responses
Correlate with server logs using trace ID
Monitor response times for timeout issues

4. Common Pitfalls

Issue

Solution

Missing array wrapper

Request body must be an array: [{...}] not {...}

Case sensitivity

Field names are case-sensitive: use CustomerId not customerid

Null handling

Use null for empty values, not undefined

Date format

Use ISO-8601: 2024-12-22T10:30:00Z

Boolean values

Use true/false, not strings "true"/"false"

Currency format

Use ISO 4217 codes: USD not $ or usd

Language format

Use IETF tags: en-US not English

📞 When to Contact Support

Reach out to our support team if you experience:

Persistent Issues

500 errors that continue after multiple retry attempts
Consistent timeout errors with small payloads
Rate limiting issues despite following best practices

Unexpected Behavior

404 errors for resources you know exist
Authentication failures with valid credentials
Error messages that don't match this documentation

When contacting support, please provide:

Your tenant ID
Timestamp when the issue occurred (in UTC)
Full error response (sanitized to remove sensitive data)
Request payload example (sanitized)
Expected vs actual behavior

Contact: support@replen.it

PreviousCustomers NextGoogle Cloud Storage Data Transfer API

Last updated 6 days ago

hashtag📊 Error Response Structure

hashtag🏷️ Error Code Categories

hashtagHTTP Status Codes

hashtag❌ Common Error Scenarios

hashtag1. Missing Required Fields (400)

hashtag2. Field Length Exceeded (400)

hashtag3. Tenant Not Found (404)

hashtag4. Resource Not Found (404)

hashtag5. Storage/Delete Failure (500)

hashtag6. Internal Server Error (500)

hashtag6. Invalid Request Format (400)

hashtag✅ How Request Validation Works

hashtagWhat We Check

hashtagWhen Validation Fails

hashtagBest Practice

hashtag🔍 Validation Error Decoder

hashtagUnderstanding Error Field Paths

hashtagCommon Validation Errors & Fixes

hashtagField Requirements by Endpoint

hashtagProducts API

hashtagCustomers API

hashtagOrders API

hashtagQuick Fixes Checklist

hashtag💡 Best Practices for Error Handling

hashtagClient-Side Implementation

hashtagValidation Before Submission

hashtag✅ Pre-Flight Validation

hashtagCustomer Validation Script

hashtagOrder Validation Script

hashtag1. Check Request Headers

hashtag2. Validate JSON Structure

hashtag3. Enable Detailed Logging

hashtag4. Common Pitfalls

hashtag📞 When to Contact Support

hashtag🔗 Related Resources

📊 Error Response Structure

🏷️ Error Code Categories

HTTP Status Codes

❌ Common Error Scenarios

1. Missing Required Fields (400)

2. Field Length Exceeded (400)

3. Tenant Not Found (404)

4. Resource Not Found (404)

5. Storage/Delete Failure (500)

6. Internal Server Error (500)

6. Invalid Request Format (400)

✅ How Request Validation Works

What We Check

When Validation Fails

Best Practice

🔍 Validation Error Decoder

Understanding Error Field Paths

Common Validation Errors & Fixes

Field Requirements by Endpoint

Products API

Customers API

Orders API

Quick Fixes Checklist

💡 Best Practices for Error Handling

Client-Side Implementation

Validation Before Submission

✅ Pre-Flight Validation

Customer Validation Script

Order Validation Script

1. Check Request Headers

2. Validate JSON Structure

3. Enable Detailed Logging

4. Common Pitfalls

📞 When to Contact Support

🔗 Related Resources