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:

• Client-side errors (4xx): request or configuration issues
• Authentication and authorization errors (401 / 403)
• Server-side errors (5xx): 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

200 OK

Request was accepted and processed successfully.

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

 

400 Bad 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

 

401 Unauthorized

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

 

403 Forbidden

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

404 Not 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

 

429 Too 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

 

500 Internal 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

 

Related Documentation

Authentication
https://replenit.gitbook.io/replenit-docs/authentication

Customers API
https://replenit.gitbook.io/replenit-docs/customers

Orders API
https://replenit.gitbook.io/replenit-docs/orders

Products API
https://replenit.gitbook.io/replenit-docs/products

Best Practices Guide
https://replenit.gitbook.io/replenit-docs/best-practices