All API errors follow a consistent envelope format. The response body contains an error object with machine-readable code, human-readable message, resolution guidance in detail, a request_id for support, and an optional field pointer. See the Error schema for the full response format.
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description.",
"detail": "Additional context and resolution guidance.",
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"field": null
}
}The code field is always one of six values: AUTHENTICATION_ERROR, INVALID_REQUEST_ERROR, RATE_LIMIT_ERROR, NOT_FOUND_ERROR, CONFLICT_ERROR, INTERNAL_ERROR. Specific error scenarios are differentiated by the message and detail fields.
When you authenticate with client credentials, the resulting access token grants access to all locations associated with your developer account. Each partner account is provisioned with a set of location IDs during onboarding. Attempting to access a location outside your partner scope returns a 403 Forbidden response with AUTHENTICATION_ERROR.
The Forbidden response includes the specific location ID that was denied, so your integration can surface a clear message to the developer or end user:
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Insufficient permissions.",
"detail": "Your API credentials do not have access to location 'd7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23'. Contact your account manager to request access.",
"request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"field": null
}
}Use GET /locations to discover which locations your credentials can access. This endpoint returns only locations within your partner scope -- if a location is missing from the list, your account does not have access to it.
Planned: Granular per-partner configuration of feature access and tender restriction enforcement is planned (
x-status: planned). When available, partner accounts will be able to configure which features and payment tenders are enabled per location. Plan your integration to handle cases where specific features may be restricted at the partner level. Current behavior: all enabled features are available at all locations in your scope.
The request is malformed or missing required fields. Check the field property for the specific field that caused the error, and detail for resolution guidance.
{
"error": {
"code": "INVALID_REQUEST_ERROR",
"message": "Request validation failed.",
"detail": "The field 'quantity' must be a positive integer.",
"request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"field": "items[0].quantity"
}
}| Code | Message | When | Retry? |
|---|---|---|---|
INVALID_REQUEST_ERROR | Request validation failed | A field has an invalid type or format (e.g., string instead of integer, invalid UUID) | Fix request |
INVALID_REQUEST_ERROR | Malformed JSON in request body | Request body is not valid JSON | Fix request |
INVALID_REQUEST_ERROR | Missing required field: {field} | A required field was omitted from the request body (e.g., grant_type, location_id) | Fix request |
INVALID_REQUEST_ERROR | Invalid parameter format | A query parameter has an invalid format (e.g., non-UUID path parameter, non-integer limit) | Fix request |
Authentication failed. The access token is missing, invalid, or expired. Request a new token via POST /auth/token.
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Invalid or expired access token.",
"detail": "The provided Bearer token has expired. Request a new token via POST /auth/token.",
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"field": null
}
}| Code | Message | When | Retry? |
|---|---|---|---|
AUTHENTICATION_ERROR | Missing authorization header | No Authorization header provided in the request | Re-authenticate |
AUTHENTICATION_ERROR | Invalid or expired access token | The Bearer token is expired or has been revoked | Re-authenticate |
AUTHENTICATION_ERROR | Invalid client credentials | The client_id or client_secret is incorrect on the token endpoint | Fix credentials |
AUTHENTICATION_ERROR | Malformed authorization header | The Authorization header does not follow the Bearer {token} format | Fix request |
The authenticated client does not have permission to access this resource. Verify that the target resource belongs to a location within your partner scope.
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Insufficient permissions.",
"detail": "Your API credentials do not have access to location 'd7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23'. Contact your account manager to request access.",
"request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"field": null
}
}| Code | Message | When | Retry? |
|---|---|---|---|
AUTHENTICATION_ERROR | Insufficient permissions | Your credentials do not have the required permissions for this operation | Contact support |
AUTHENTICATION_ERROR | Location not in partner scope | The target location is not associated with your developer account | Contact account manager |
AUTHENTICATION_ERROR | Resource belongs to another partner | Attempting to access a cart, order, or webhook owned by a different partner | Fix request |
The requested resource does not exist. Verify the resource ID and that it belongs to a location your credentials can access.
{
"error": {
"code": "NOT_FOUND_ERROR",
"message": "Resource not found.",
"detail": "No location found with ID 'd7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23'.",
"request_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"field": null
}
}| Code | Message | When | Retry? |
|---|---|---|---|
NOT_FOUND_ERROR | Cart not found | The cart ID does not exist or the cart has been deleted | Fix request |
NOT_FOUND_ERROR | Order not found | The order ID does not exist or belongs to another partner | Fix request |
NOT_FOUND_ERROR | Location not found | The location ID does not exist or is not in your partner scope | Fix request |
NOT_FOUND_ERROR | Menu item not found | The menu item ID does not exist at this location | Fix request |
The request conflicts with the current state of the resource. Common causes include modifying a checked-out cart, reusing an idempotency key with a different payload, or a price mismatch at checkout.
{
"error": {
"code": "CONFLICT_ERROR",
"message": "Cart has already been checked out.",
"detail": "Cart c1d2e3f4-a5b6-7890-cdef-1234567890ab is in CHECKED_OUT status and cannot be modified.",
"request_id": "b3c4d5e6-f7a8-9012-cdef-345678901234",
"field": null
}
}| Code | Message | When | Retry? |
|---|---|---|---|
CONFLICT_ERROR | Cart has already been checked out | Attempting to modify a cart with status CHECKED_OUT or ABANDONED | No -- use the existing order |
CONFLICT_ERROR | Idempotency key conflict | The Idempotency-Key was previously used with a different request body | Use a new UUID |
CONFLICT_ERROR | Promo code already applied | A promo code is already active on this cart. Remove the current code before applying a new one. | No -- remove existing code first |
CONFLICT_ERROR | Expected total mismatch | The expected_total in the checkout request does not match the current cart total. The change_reasons array explains what changed (e.g., PROMO_EXPIRED, DISCOUNT_CHANGED, FEE_CHANGED, ITEM_PRICE_CHANGED, ITEM_UNAVAILABLE). | Re-calculate and retry |
CONFLICT_ERROR | Duplicate webhook subscription | A webhook subscription already exists for this URL and event type combination | No -- use existing subscription |
The request is well-formed but violates a business rule. Fix the issue described in the detail field and retry.
{
"error": {
"code": "INVALID_REQUEST_ERROR",
"message": "Cart validation failed.",
"detail": "Modifier group 'Bread Choice' requires exactly 1 selection but 0 were provided.",
"request_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"field": "items[0].modifier_selections"
}
}| Code | Message | When | Retry? |
|---|---|---|---|
INVALID_REQUEST_ERROR | Modifier validation failed | Modifier selections violate min_selections or max_selections constraints for a modifier group | No -- adjust selections |
INVALID_REQUEST_ERROR | Item is not available | The menu item is currently unavailable (out of stock, disabled, or outside sale hours) | No -- remove item |
INVALID_REQUEST_ERROR | Quantity exceeds limit | The requested quantity exceeds the item's max_allowed_quantity | No -- reduce quantity |
INVALID_REQUEST_ERROR | Cart is empty | Attempted to calculate prices or checkout with an empty cart | No -- add items first |
INVALID_REQUEST_ERROR | Missing handoff mode | Checkout attempted without a handoff mode set on the cart or in the request body | No -- set handoff mode |
INVALID_REQUEST_ERROR | Payment declined | The payment processor declined the transaction (insufficient funds, invalid card, etc.) | No -- try a different payment method |
INVALID_REQUEST_ERROR | Refund exceeds refundable balance | The refund amount exceeds total_paid - total_refunded on the order | No -- reduce refund amount |
INVALID_REQUEST_ERROR | Payment required | The order total has not been fully covered by submitted payments | No -- submit additional payment |
INVALID_REQUEST_ERROR | Invalid tender for item | A payment method not listed in the item's allowed_tenders was used (planned feature) | No -- use an allowed payment method |
INVALID_REQUEST_ERROR | Invalid delivery address | The delivery address is missing required fields or has an invalid format | No -- fix address fields |
INVALID_REQUEST_ERROR | Promo code not recognized | The promo code does not exist in the system (rejection_reason: INVALID_CODE) | No -- check code spelling |
INVALID_REQUEST_ERROR | Promo code expired | The promo code has passed its expiration date (rejection_reason: EXPIRED) | No -- code cannot be used |
INVALID_REQUEST_ERROR | Promo code already used | This single-use promo code has already been redeemed (rejection_reason: ALREADY_USED) | No -- code cannot be reused |
INVALID_REQUEST_ERROR | Minimum not met for promo code | The cart subtotal is below the promo code's minimum purchase requirement (rejection_reason: MINIMUM_NOT_MET) | No -- add more items |
INVALID_REQUEST_ERROR | Promo code not applicable | No eligible items in the cart for this promo code (rejection_reason: NOT_APPLICABLE) | No -- add eligible items |
INVALID_REQUEST_ERROR | Customer ID too long | The customer_id value exceeds the maximum length (255 characters) | No -- shorten customer_id |
INVALID_REQUEST_ERROR | Invalid customer ID format | The customer_id contains invalid characters (must be alphanumeric, hyphens, and underscores only) | No -- fix format |
INVALID_REQUEST_ERROR | Below minimum order amount | The cart subtotal is below the location's minimum for the selected handoff mode (server auto-applies SMALL_ORDER fee instead of blocking) | No -- informational only (fee is auto-applied) |
Promo code errors: See the Promotions, Fees & Discounts guide for the full rejection reason table with UX suggestions.
Rate limit exceeded. Wait for the duration specified in the Retry-After response header before making another request.
{
"error": {
"code": "RATE_LIMIT_ERROR",
"message": "Rate limit exceeded.",
"detail": "You have exceeded 100 requests per minute. Wait 60 seconds before retrying.",
"request_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
"field": null
}
}| Code | Message | When | Retry? |
|---|---|---|---|
RATE_LIMIT_ERROR | Rate limit exceeded | Global or per-endpoint rate limit exceeded | Retry with backoff -- use Retry-After header |
RATE_LIMIT_ERROR | Too many token requests | Token endpoint rate limit exceeded (cache tokens instead of re-authenticating per request) | Retry with backoff -- implement token caching |
An unexpected error occurred on the server. Retry with exponential backoff. If the problem persists, contact Tote Developer Support with the request_id.
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred.",
"detail": "Please retry your request. If the problem persists, contact developer@totepos.com with the request_id.",
"request_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
"field": null
}
}| Code | Message | When | Retry? |
|---|---|---|---|
INTERNAL_ERROR | An unexpected error occurred | Server-side error during request processing | Retry with backoff |
INTERNAL_ERROR | Service temporarily unavailable | A downstream service is unavailable (e.g., payment processor, inventory service) | Retry with backoff |
- Rate Limiting Reference -- Rate limit tiers, backoff strategy, and 429 response details.
- Getting Started Guide -- Error handling overview and error category summary table.
- Error schema -- OpenAPI schema definition for the error response envelope.