Errors
Handle Melo API failures consistently and decide when requests are safe to retry.
All API errors use the same JSON envelope:
{
"type": "WAREHOUSE_NOT_FOUND",
"message": "Warehouse not found",
"code": 404
}| Field | Description |
|---|---|
type | Stable machine-readable error identifier when provided by the API. |
message | Human-readable description intended for developers. |
code | HTTP status code repeated in the response body. |
Status codes
| Code | Meaning | Client behavior |
|---|---|---|
400 | Invalid input or invalid resource state | Correct the request; do not retry unchanged. |
401 | Missing, invalid, expired, or revoked credentials | Refresh the token when expired; otherwise stop and inspect credentials. |
403 | The merchant cannot access the resource | Do not retry without changing credentials or resource ownership. |
404 | The requested resource does not exist | Verify the identifier and environment. |
500 | Unexpected server failure | Retry with exponential backoff when the operation is safe to repeat. |
Common business errors
| Type | Endpoint | Meaning |
|---|---|---|
WAREHOUSE_NOT_FOUND | Warehouse operations, options | The warehouse ID does not exist. |
WAREHOUSE_NOT_ACTIVE | Options | The selected warehouse is disabled. |
WAREHOUSE_HAS_TRANSFERS_ASSOCIATED | Delete warehouse | Historical transfers prevent deletion. |
NO_PRODUCTS_FOUND | Options | No delivery product is available for the request. |
MATCHMAKING_NOT_FOUND | Create transfer | The quote ID does not exist. |
MATCHMAKING_INCORRECT_STATUS | Create transfer | The quote has already been consumed or is not pending. |
PRODUCT_NOT_FOUND | Create transfer | The product key was not returned by that quote. |
DELIVERY_OPTION_PRICE_NOT_FOUND | Create transfer | The selected product has no payable price. |
TRANSFER_NOT_FOUND | Get transfer | The transfer does not exist or is not an API-created transfer. |
Retry safety
GET requests are safe to retry. Token and quote requests may be retried after transient network failures. Transfer creation changes state and charges the merchant balance, so treat a timeout as an unknown result and avoid automatic retries until you can establish whether the transfer was created.