API Reference

Error Responses

Standard error formats, status codes, and handling guidelines for the Replenit Ingestion API

Overview

All Replenit API endpoints return structured error responses when a request cannot be processed.

Errors fall into three categories:

4xxClient-side errors: request or configuration issues
401/403Authentication and authorization errors
5xxServer-side errors: transient or internal failures

Upstream systems are expected to interpret errors programmatically and apply appropriate retry or correction logic.

Error Response Structure

Validation Error Format (RFC 7231)

For validation errors, Replenit returns a structured response aligned with RFC 7231.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-abc123…",
  "errors": {
    "[0].CustomerId": [
      "The CustomerId field is required."
    ]
  }
}

Generic Error Envelope

For non-validation errors, a simplified response envelope is returned.

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

HTTP Status Codes

200OK

Request was accepted and processed successfully.

Returned even when some records inside a batch are ignored or skipped due to business logic.

400Bad Request

The request payload is invalid.

Common Causes:

• Missing required fields
• Missing required identifier
• Field length exceeded
• Invalid data types
• Invalid date, currency, or language format

Example:

{
  "status": 400,
  "errors": {
    "": [
      "At least one of the following properties must have a value: CustomerId, Email"
    ]
  }
}

Handling:

Do not retry
Fix the payload and resend

401Unauthorized

Authentication failed.

Common Causes:

• Missing x-replenit-auth-key header
• Invalid or revoked API key
• Malformed API key value

Example:

{
  "success": false,
  "message": "Unauthorized.",
  "data": {}
}

Handling:

• Verify API key
• Ensure header is present
• Regenerate key if necessary

403Forbidden

API key is valid but does not have access to the tenant.

Common Causes:

• API key is not associated with the target tenant
• Tenant access revoked

Example:

{
  "success": false,
  "message": "Access denied.",
  "data": {}
}

Handling:

• Verify tenant ID
• Confirm API key permissions
• Contact platform administrator or Replenit CSM

404Not Found

The referenced resource does not exist.

Common Causes:

• Tenant ID does not exist
• Deleting a non-existent customer, order, or product

Example:

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

Handling:

• Verify tenant ID
• Verify resource identifier
• Do not retry unless configuration changes

429Too Many Requests

Rate limit exceeded.

Example:

{
  "success": false,
  "message": "Rate limit exceeded.",
  "data": {}
}

Headers may include:

Retry-After
X-RateLimit-Remaining
X-RateLimit-Reset

Handling:

• Apply exponential backoff
• Respect Retry-After
• Reduce request frequency
• Use batching

500Internal Server Error

Unexpected server-side failure.

Example:

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

Handling:

• Retry with exponential backoff
• Preserve idempotency
• If persistent, contact support

Common Validation Errors

Missing Identifier

Occurs when neither primary nor alternative identifier is provided.

{
  "status": 400,
  "errors": {
    "": [
      "At least one of the following properties must have a value: CustomerId, Email"
    ]
  }
}

Resolution:

• Provide at least one identifier
• Ensure alignment with tenant identifier configuration

Field Length Exceeded

{
  "status": 400,
  "errors": {
    "[0].OrderId": [
      "The field OrderId must be a string with a maximum length of 100."
    ]
  }
}

Resolution:

• Truncate or normalize identifiers
• Enforce limits upstream

Invalid Nested Fields

{
  "status": 400,
  "errors": {
    "[0].OrderItems[0].ProductId": [
      "The ProductId field is required."
    ]
  }
}

Resolution:

• Validate nested arrays before submission
• Ensure required fields are present for each item

Retry Strategy Summary

Status	Retry	Notes
400	No	Fix payload
401	No	Fix authentication
403	No	Fix access
404	No	Verify identifiers
429	Yes	Backoff + retry
500	Yes	Backoff + retry

Observability and Debugging

Each error response may include a traceId.

When contacting support, provide:

Tenant ID
Timestamp (UTC)
Endpoint and method
Request payload (sanitized)
Full error response
Trace ID (if present)

Operational Notes

Partial batch failures are returned as validation errors
Replenit does not auto-correct invalid payloads
Identifier misalignment is a common source of ingestion issues

Error Responses

Overview

Error Response Structure

Validation Error Format (RFC 7231)

Generic Error Envelope

HTTP Status Codes

Common Causes:

Example:

Handling:

Common Causes:

Example:

Handling:

Common Causes:

Example:

Handling:

Common Causes:

Example:

Handling:

Example:

Headers may include:

Handling:

Example:

Handling:

Common Validation Errors

Missing Identifier

Resolution:

Field Length Exceeded

Resolution:

Invalid Nested Fields

Resolution:

Retry Strategy Summary

Observability and Debugging

Operational Notes

Related Documentation

Authentication

Customers API

Orders API

Products API

Best Practices

Rate Limits

Need help or have questions?