Skip to main content
Errors use the HTTP status code and a JSON body with the failure message.

​
Authentication errors

Missing API key: 
{
  "statusCode": 401,
  "message": "Missing x-api-key header",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "path": "/api/v1/products"
}
Invalid or inactive API key: 
{
  "statusCode": 401,
  "message": "Invalid or inactive API key",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "path": "/api/v1/products"
}
Missing required x-partner-id header: 
{
  "statusCode": 400,
  "message": "x-partner-id header is required",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "path": "/api/v1/orders"
}

​
Validation errors

The API rejects unknown fields and invalid types. Example request with an invalid pincode: 
curl -X POST https://dev-api.keystonecommerce.in/api/v1/users/me/addresses \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <integration_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "221B MG Road",
    "city": "Bengaluru",
    "state": "Karnataka",
    "pincode": "5600"
  }'
Response: 
{
  "statusCode": 400,
  "message": [
    "pincode must be longer than or equal to 6 characters"
  ],
  "error": "Bad Request",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "path": "/api/v1/users/me/addresses"
}

​
Idempotency conflicts

If an x-idempotency-key is reused with a different checkout payload, the API returns a conflict. 
{
  "statusCode": 409,
  "message": "Checkout idempotency key has already been used with a different payload",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "path": "/api/v1/orders"
}

​
Common HTTP statuses

StatusMeaning
400Invalid request, missing required integration header, or failed business rule
401Missing or invalid authentication
404Resource not found for the current customer or integration context
409Conflict, usually an idempotency or state transition conflict
413Uploaded file is too large
429Request was rate limited
500Internal server error