Error Reference

All Connect API errors follow RFC 9457 Problem Detail format. Use the type field to programmatically handle errors in your integration.

Error Format

json

{
  "type": "VALIDATION_ERROR",
  "title": "Validation failed",
  "status": 422,
  "detail": "Field 'name' is required.",
  "instance": "/connect/v1/supplier/catalog/products"
}

Field	Description
`type`	Machine-readable error code. Use this in your switch/case logic.
`title`	Short human-readable summary.
`status`	HTTP status code.
`detail`	Detailed explanation with specifics (e.g., which field failed).
`instance`	The API endpoint that produced the error.

HTTP Status Codes

Code	Meaning	Action
`200`	OK	Request succeeded.
`201`	Created	Resource created successfully.
`400`	Bad Request	Check request body and parameters.
`401`	Unauthorized	API key is missing, invalid, or expired.
`403`	Forbidden	Key lacks required scope for this endpoint.
`404`	Not Found	Resource does not exist or belongs to another tenant.
`405`	Method Not Allowed	Wrong HTTP method for this path. Check the endpoint docs.
`409`	Conflict	Version / lock / duplicate conflict (e.g. ORDER_VERSION_CONFLICT, CONFLICT_OPTIMISTIC_LOCK, DATA_INTEGRITY_VIOLATION, IDEMPOTENCY_KEY_REUSED). Re-read and retry. Note: STOCK_INSUFFICIENT is 422, not 409.
`410`	Gone	Resource was permanently removed (e.g. an erased Studio instance). Do not retry.
`413`	Payload Too Large	Request body exceeds 2 MB. Split into smaller batches.
`415`	Unsupported Media Type	Send Content-Type: application/json on JSON endpoints.
`422`	Unprocessable Entity	Validation or business-rule error (incl. STOCK_INSUFFICIENT). Check the detail field.
`429`	Too Many Requests	Rate limited. Check X-RateLimit-Reset header.
`500`	Internal Server Error	Server error. Retry with exponential backoff.

Error Types

The following error types may appear in the type field:

Type	Status	Description
`VALIDATION_ERROR`	`422`	Request body or parameters failed validation.
`MALFORMED_REQUEST`	`400`	Request body is not valid JSON or cannot be parsed.
`MISSING_PARAMETER`	`400`	A required query or path parameter is missing.
`TYPE_MISMATCH`	`400`	A parameter has the wrong type (e.g. a non-numeric order id).
`INVALID_ARGUMENT`	`400`	An argument value is invalid for this endpoint.
`UNAUTHORIZED`	`401`	No valid credentials — the API key or token is missing, malformed, revoked, or expired.
`FORBIDDEN`	`403`	Credential is valid but lacks the required scope or side for this endpoint.
`NOT_FOUND`	`404`	The requested resource does not exist or belongs to another tenant. Domain lookups use the <ENTITY>_NOT_FOUND convention (ORDER_NOT_FOUND, PRODUCT_NOT_FOUND, ...).
`METHOD_NOT_ALLOWED`	`405`	Wrong HTTP method for this path.
`UNSUPPORTED_MEDIA_TYPE`	`415`	Content-Type is not application/json on a JSON endpoint.
`PAYLOAD_TOO_LARGE`	`413`	Request body exceeds the 2 MB limit. Split into smaller batches.
`STOCK_INSUFFICIENT`	`422`	Not enough stock to fulfill the request.
`ORDER_CANNOT_CANCEL`	`422`	The order has moved past PREPARING — cancellation is no longer a valid transition.
`MEDIA_TYPE_NOT_SUPPORTED`	`422`	Image content type is not image/jpeg, image/png, or image/webp.
`MEDIA_TOO_LARGE`	`422`	Image exceeds 5 MB. Resize before uploading.
`MEDIA_HANDLE_INVALID`	`422`	The upload handle does not belong to this product, or the digest does not match the one it was issued for. Request a new upload URL.
`INVALID_LINK_CODE`	`422`	The Studio link code is invalid or expired.
`INSTANCE_ALREADY_LINKED`	`409`	This Studio instance is already linked to a tenant.
`INSTANCE_RECONCILE_REQUIRED`	`409`	The Studio instance state diverged and must reconcile before continuing.
`INSTANCE_GONE`	`410`	The Studio installation was removed by an administrator. Contact support to restore it.
`AMENDMENT_IN_FLIGHT`	`422`	Order has a pending buyer amendment. Wait for the buyer to accept or reject before dispatching, cancelling, or amending again.
`CREDIT_LIMIT_EXCEEDED`	`422`	Buyer's order would exceed their credit limit with the supplier (Q5b).
`CREDIT_HOLD`	`422`	Buyer's credit account is on hold by the supplier (Q5b).
`DUPLICATE_EXTERNAL_ID`	`422`	A product with this externalId already exists (use upsert).
`PRICE_NOT_SUPPORTED_VIA_CONNECT`	`422`	The catalog payload carried unitPrice or currency. A product has no single price here — pricing is per buyer through price lists, managed in the supplier portal. Remove both fields.
`ORDER_VERSION_CONFLICT`	`409`	The If-Match token no longer matches the order: it changed since you read it. Re-read the order and decide again.
`CONFLICT_OPTIMISTIC_LOCK`	`409`	Resource was modified by another request between read and write. Reload and retry.
`DATA_INTEGRITY_VIOLATION`	`409`	Request conflicts with existing data (unique constraint, FK, etc.). It may already exist.
`IDEMPOTENCY_KEY_REUSED`	`409`	This Idempotency-Key was already used with a different request body. Retrying the identical request replays the stored response; a different body needs a fresh key.
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests. Slow down and retry after the reset window.
`INTERNAL_ERROR`	`500`	Unexpected server error. Contact support if persistent.

Retry Strategy

On receiving HTTP 429, wait until the time specified in X-RateLimit-Reset (Unix epoch seconds). Add random jitter (0-1 second) to prevent thundering herd. For 5xx errors, use exponential backoff starting at 1 second.

Rate Limiting

When rate limited, the response includes headers to help you handle the limit:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.
`Retry-After`	Seconds to wait before retrying (only on 429 responses).

response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711015260
Retry-After: 45
Content-Type: application/problem+json

{
  "type": "RATE_LIMIT_EXCEEDED",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Rate limit reached. Retry after 45 seconds.",
  "instance": "/connect/v1/supplier/catalog/products"
}

Error Handling Best Practices

1.Always check the type field — use it as your primary error discriminator, not the HTTP status code alone.
2.Implement exponential backoff for 429 and 5xx errors. Start with 1 second and double on each retry.
3.Use idempotency keys on all mutating requests so retries are safe.
4.Log the full error response including the instance field for debugging.
5.Never retry 4xx errors (except 429) without changing the request. They indicate a client-side issue.