Errors - Keystone Commerce API Docs

Errors use the HTTP status code and a JSON body with the failure message. Some errors also include a machine-readable code.

Authentication errors

Requests without valid authentication return 401. See Authentication for the supported methods. Invalid or inactive Partner 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"
}

Unprovisioned External user ID:

{
  "statusCode": 401,
  "message": "Unknown partner customer identity",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "path": "/api/v1/orders"
}

Server authentication not enabled for your partner:

{
  "statusCode": 403,
  "message": "Partner server authentication is not enabled",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "path": "/api/v1/orders"
}

Provisioning details that conflict with an existing customer identity:

{
  "statusCode": 409,
  "message": "Partner identity does not match the existing customer account",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "path": "/api/v1/partner/users/resolve"
}

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 "Content-Type: application/json" \
  -d '{
    "recipientName": "Aarav Sharma",
    "recipientPhone": "9876543210",
    "label": "Home",
    "line1": "221B MG Road",
    "city": "Bengaluru",
    "state": "Karnataka",
    "pincode": "5600",
    "landmark": "Near Trinity Metro"
  }'

Response:

{
  "statusCode": 400,
  "message": [
    "pincode must be a 6-digit Indian pincode"
  ],
  "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

Status	Meaning
`400`	Invalid request, missing `x-partner-id`, or failed business rule
`401`	Missing or invalid authentication
`403`	Authenticated, but the action is not allowed, for example when server authentication is not enabled
`404`	Resource not found for the current customer or Partner ID
`409`	Conflict, usually an idempotency, identity, or state transition conflict
`413`	Request body is larger than 1 MB. An evidence image over the size limit returns `400` instead.
`429`	Request was rate limited
`500`	Internal server error
`503`	A required dependency is temporarily unavailable. Retry with backoff.

​Authentication errors

​Validation errors

​Idempotency conflicts

​Common HTTP statuses

Authentication errors

Validation errors

Idempotency conflicts

Common HTTP statuses