Integration reference

Errors & retries

Use the HTTP status and the JSON code to decide whether to correct the request, check access, or retry. Every endpoint response includes a UTC request timestamp.

HTTP status	Meaning	What to do
200	Inventory lookup completed, or an order was already received.	Read products and metadata, or inspect `duplicate`.
201	New order received and queued.	Record the external order ID. This is not fulfillment confirmation.
400	Invalid parameters, JSON, or order fields.	Correct the request before retrying.
401	Invalid, inactive, revoked, or missing credentials.	Verify Basic Auth credentials with Medidenta.
403	Missing permission, or conflicting order source.	Check Read/Write access; omit source_id from orders.
404	No requested SKUs have an accessible match.	Check the SKU spelling and assigned catalog. Not a reason to clear other products.
405	Wrong HTTP method.	Use GET for inventory, POST for orders. The Allow header names the method.
409	No unambiguous inventory matches.	Contact Medidenta about duplicate SKU mappings.
500	Server could not complete the request.	Retry after a delay. Reuse the same external order ID for orders.

Example error response

401 Unauthorized

{
  "success": false,
  "code": "unauthorized",
  "message": "Invalid API credentials.",
  "request_timestamp": "2026-11-10T22:05:00Z"
}

Do not assume every error contains products or meta. Inventory lookup results (including 404 and 409) include those fields; authentication and validation errors generally do not.

Inventory error codes

Code	HTTP status	Meaning
`unauthorized`	401	Basic Auth failed or the key is unavailable.
`insufficient_permissions`	403	Key lacks Read permission.
`invalid_parameters`	400	Query contains parameters other than sku.
`invalid_skus`	400	Empty, malformed, or oversized SKU input.
`not_found`	404	No requested products are accessible.
`ambiguous_sku`	409	Only ambiguous matches were found.
`method_not_allowed`	405	Use GET.
`server_error`	500	Unable to retrieve inventory.

Order error codes

Code	HTTP status	Meaning
`unauthorized`	401	Basic Auth failed or the key is unavailable.
`insufficient_permissions`	403	Key lacks Write permission.
`source_mismatch`	403	Provided source_id differs from the key’s assigned source.
`empty_body`	400	Request body is empty.
`invalid_json`	400	Request body is not a valid JSON object.
`missing_external_order_id`	400	Order ID is missing, empty, or not a string/integer.
`invalid_queue_status`	400	Unsupported queue status or invalid type.
`method_not_allowed`	405	Use POST.
`server_error`	500	Unable to receive the order; retry using the same ID.

Practical retry rules

On 400, 401, 403, 404, 405, or 409, investigate the request or access configuration instead of retrying continuously.
On a transient network error or 500, use a small, bounded number of retries with increasing delays.
For order retries, always reuse the original external order ID.
For inventory, keep your last successful sync if the next pull fails. Never interpret an error response as an empty catalog.

When contacting Medidenta

Include the endpoint, HTTP status, JSON error code, request timestamp, and affected SKU or external order ID. Do not include your consumer secret or Authorization header.