Copy page

Marketfront API

API Conventions

This section covers the core mechanics of the Marketfront API, including error handling, rate limiting, and caching.

Authentication

All requests require a Bearer token in the Authorization header. See the Authentication guide for key management, environment setup, and security best practices.

Error Handling

All error responses use RFC 9457 application/problem+json format. Every error includes machine-readable fields (errorCategory, retryable, retryAfter) for programmatic handling. Domain-specific errors include an errorCode field identifying the specific issue.

The API supports content negotiation via the Accept header — request text/markdown for a compact text representation suitable for AI agents and CLI tooling. See the Error Reference for full details.

HTTP Status Codes

Status	Meaning
400	Invalid request body, missing fields, or domain-specific errors (see errorCode)
401	Missing or invalid API key
404	Resource does not exist
409	Conflict (e.g., order token already used)
422	Validation failed (see errors array)
429	Rate limit exceeded
500	Unexpected server error

Error Codes

Domain-specific errors include an errorCode field.

Cart & Item Errors

Code	Description	Action
CART_EMPTY	Cart has no items	Add items before validating
CATALOGSET_REQUIRED	Cart creation requires a catalogSetId	Include catalogSetId when cart is null
ITEM_UNAVAILABLE	Item no longer available	Remove from cart and re-validate
MODIFIER_REQUIRED	Required modifier group has no selection	Prompt user to select
ORDER_BELOW_MINIMUM	Below store's order minimum	Add more items

Store Errors

Code	Description	Action
STORE_CLOSED	Store is no longer open	Re-discover stores
STORE_NOT_FOUND	Store does not exist	Re-discover stores
CATALOGSET_NOT_FOUND	CatalogSet does not exist	Re-discover for updated catalogSetId

Payment Errors

Code	Description	Action
PAYMENT_FAILED	Transient processing failure	Retry with the same idempotency key
PAYMENT_METHOD_INVALID	Payment method payload not valid	Re-prompt the user for payment details
PAYMENT_DECLINED	Declined by issuer	Use a different payment method

Order Errors

Code	Description	Action
ORDER_TOTAL_DIFFERENT	Total changed since validation	Re-validate the order
ORDER_ALREADY_PLACED	Idempotency-key conflict	This order was already placed

Address Errors

Code	Description	Action
ADDRESS_INVALID	Could not be validated	Verify the address
ADDRESS_OUT_OF_RANGE	Outside store's delivery zone	Choose a different store

Authentication Errors

Code	HTTP	Description	Action
SESSION_USER_REQUIRED	401	Endpoint requires an authenticated user identity	Ensure the end user is signed in before making this request

Retry Strategy

Category	Retryable?	Strategy
401 Unauthorized	No	Fix your API key
400 Bad Request	No	Fix the request
404 Not Found	No	Resource doesn't exist
429 Too Many Requests	Yes	Wait for X-RateLimit-Reset, then retry
500 Internal Error	Yes	Exponential backoff (1s, 2s, 4s, max 30s)

Always include the requestId when contacting support about a specific error.

Rate Limits

Per-partner rate limits ensure fair usage and platform stability.

Endpoint Type	Limit	Examples
Read operations	1,000/min	/stores/discover, /catalog-sets/{catalogSetId}
Write operations	100/min	/orders/validate, /orders/place
Store discovery	60/min	/stores/discover (also counted under reads)

Sandbox rate limits are 5x higher than production.

Rate limits are scoped to your partner organization — all keys belonging to the same organization share the same quota.

Every response includes rate limit headers:

Header	Description
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

When rate limited, the API returns 429 Too Many Requests. Read the X-RateLimit-Reset header to know when to retry. If the header is missing, use exponential backoff starting at 1 second.

Caching Strategy

Data Type	Strategy	Why
Store results	Never cache	Store status changes constantly
CatalogSets	Cache aggressively	Immutable — use catalogSetId as cache key
Validation tokens	Expire in 15 min	Security and price accuracy