Error Codes
The Sellvy API uses conventional HTTP status codes and returns structured error objects so your integration can handle failures programmatically. Every error response follows the same predictable format.
Error response format
When a request fails, the API returns a JSON object with success: false and an error object containing a machine-readable code and a human-readable message:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "title, type, and price are required"
}
}code field for programmatic branching, not the message string. Messages may change without notice, but error codes are stable.Error codes reference
| Code | HTTP Status | Description | When it happens |
|---|---|---|---|
UNAUTHORIZED | 401 | Invalid or missing API key | API key not provided in the X-API-Key header, invalid, or expired |
FORBIDDEN | 403 | Insufficient permissions | API key lacks the required permission (e.g., write access for mutations) |
NOT_FOUND | 404 | Resource not found | The requested ID does not exist or does not belong to your store |
VALIDATION_ERROR | 400 | Invalid request body | Missing required fields, invalid field values, or malformed JSON |
RATE_LIMITED | 429 | Rate limit exceeded | Too many requests in the current window — check the Retry-After header |
PLAN_LIMIT_REACHED | 403 | Plan quota exceeded | Product limit reached or feature not available on your current plan |
INTERNAL_ERROR | 500 | Server error | An unexpected error occurred — retry the request or contact support if persistent |
HTTP status code conventions
The Sellvy API uses standard HTTP status codes grouped into three categories:
2xx — Success
The request was accepted and processed successfully. 200 for reads and updates, 201 for resource creation, and 204 for successful deletions with no response body.
4xx — Client error
The request was invalid due to missing or incorrect parameters, insufficient permissions, or resource not found. These errors are deterministic and will not succeed if retried without changes.
5xx — Server error
Something went wrong on our end. These are rare and typically transient. Retry the request with exponential backoff. If the error persists, contact [email protected].
Handling errors in code
Check the success field and branch on the error.code to handle each case appropriately:
async function createProduct(product) {
const response = await fetch("https://sellvy.io/api/v1/products", {
method: "POST",
headers: {
"X-API-Key": process.env.SELLVY_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify(product)
});
const body = await response.json();
if (!body.success) {
switch (body.error.code) {
case "VALIDATION_ERROR":
console.error("Invalid input:", body.error.message);
break;
case "UNAUTHORIZED":
console.error("Check your API key");
break;
case "PLAN_LIMIT_REACHED":
console.error("Upgrade your plan:", body.error.message);
break;
case "RATE_LIMITED":
const retryAfter = response.headers.get("Retry-After");
console.error(`Rate limited. Retry in ${retryAfter}s`);
break;
default:
console.error("API error:", body.error.code, body.error.message);
}
return null;
}
return body.data;
}RATE_LIMITED error, always respect the Retry-After header before retrying. See the Rate Limits page for details on per-plan limits and retry strategies.