Skip to main content
V2 Alpha — This error format is part of the V2 API preview. Breaking changes may occur.

​
Overview

All V2 API endpoints return a consistent error format. Errors always include success: false and an error object with a human-readable message and a machine-readable code.

​
Error Response Format

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

​
HTTP Status Codes

StatusDescription
200Success
201Resource created
400Bad request — invalid parameters or missing required fields
401Unauthorized — missing, invalid, or expired token
403Forbidden — accessing another vendor’s data or a merchant-only endpoint
404Not found — resource does not exist
409Conflict — resource creation/update conflict
429Too many requests — rate limit exceeded
500Internal server error

​
Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid vendor API key or expired token
FORBIDDEN403Attempting to access another vendor’s data or a merchant-only endpoint
NOT_FOUND404Requested resource not found
VALIDATION_ERROR400Request body or query parameters failed validation
FULFILLMENT_FAILED400Fulfillment creation failed
CONFLICT409Resource creation/update conflict
INTERNAL_ERROR500Unexpected server error
Vendor tokens are automatically scoped to your data. If you receive a 403 Forbidden error, it usually means you are calling a merchant-only endpoint. Check that you are using the /v2/vendor/* routes.

​
Validation Errors

When request validation fails, the message field contains details about which fields are invalid: 
{
  "success": false,
  "error": {
    "message": "createdAtMin must be a valid ISO 8601 date",
    "code": "VALIDATION_ERROR"
  }
}

​
Rate Limiting

When you exceed 100 requests per minute, you will receive: 
{
  "success": false,
  "error": {
    "message": "Too many requests, please try again later",
    "code": "RATE_LIMITED"
  }
}
Wait at least 60 seconds before retrying.