Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt

Use this file to discover all available pages before exploring further.

V2 Preview — 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"
  }
}

​
Error Codes

CodeHTTP StatusDescriptionRetry?
UNAUTHORIZED401Invalid API key, expired token, revoked key, or inactive shopNo — re-authenticate or fix the key
FORBIDDEN403Accessing another vendor’s data, unapproved account, or insufficient scopeNo — check your permissions
NOT_FOUND404Requested resource does not existNo — verify the resource ID
VALIDATION_ERROR400Request body or query parameters failed validationNo — fix the request
FULFILLMENT_FAILED400Fulfillment creation failed (e.g., invalid line items)No — fix the request
CONFLICT409Resource creation/update conflictNo — check resource state
RATE_LIMITED429Exceeded 100 requests/minute per IPYes — exponential backoff
INTERNAL_SERVER_ERROR500Unexpected server errorYes — retry up to 3 times with backoff

​
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 insufficient scope
404Not found — resource does not exist
409Conflict — resource creation/update conflict
429Too many requests — rate limit exceeded
500Internal server error

​
Validation Errors

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

​
Rate Limiting

The API allows 100 requests per minute per IP address. The limit is per IP, not per API key. The API returns standard RateLimit-* headers on every response. When you exceed the limit: 
{
  "success": false,
  "error": {
    "message": "Too many requests, please try again later",
    "code": "RATE_LIMITED"
  }
}
Implement exponential backoff — wait 1s, then 2s, then 4s between retries.

​
Retry Guidance

StatusShould Retry?Strategy
400, 401, 403, 404, 409NoFix the request — these are client errors
429YesExponential backoff. Check RateLimit-* response headers
500YesRetry up to 3 times with exponential backoff. If persistent, contact support