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 — insufficient permissions for this operation
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 API key or expired token
FORBIDDEN403Insufficient permissions for this operation
NOT_FOUND404Requested resource not found
VALIDATION_ERROR400Request body or query parameters failed validation
VENDOR_ID_REQUIRED400Merchant token missing required vendorId parameter
FULFILLMENT_FAILED400Fulfillment creation failed
CONFLICT409Resource creation/update conflict
INTERNAL_ERROR500Unexpected server error
The VENDOR_ID_REQUIRED error is specific to merchant tokens. Some endpoints (like fulfillments and payouts) require a vendorId query parameter when using a merchant token to specify which vendor’s data to access.

​
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.