VISTARMAN
+ VPP Submit
← Return to Media Studio•DEVELOPER & EDGE API GATEWAY
OpenAPI 3.1 Spec ↗Edge Operational

Error Reference & Troubleshooting

Learn how to interpret API error codes, parse structured error responses, and implement resilient retry logic in your integrations.

Schema

Standardized Error Response Envelope

All API errors return a standard JSON object containing the HTTP status code, a machine-readable error code, and a descriptive message:

JSON Error Envelope
{
  "error": {
    "status": 400,
    "code": "VAL_SRCH_001",
    "message": "Query parameter 'q' is required and must contain at least 1 character.",
    "docs_url": "https://vistarman.com/api/errors#400"
  },
  "timestamp": "2026-08-18T12:00:00.000Z"
}

HTTP Status Codes Catalog

HTTP 400BAD_REQUEST
The request payload or query parameters are invalid or missing required fields.
Common TriggerCalling /v1/search without the required ?q= query parameter.
Recommended ResolutionEnsure required parameters are supplied and formatted properly.
HTTP 401UNAUTHORIZED
Authentication is required or the provided Bearer token is invalid or expired.
Common TriggerAccessing protected creator or partner management endpoints without a valid JWT.
Recommended ResolutionProvide a valid Authorization header: Bearer <token>. Note: Public knowledge endpoints do not require auth.
HTTP 403FORBIDDEN
The client does not have sufficient permissions to access the requested resource.
Common TriggerNon-whitelisted email trying to perform admin actions or invalid Cloudflare Turnstile token.
Recommended ResolutionVerify account permissions or submit a valid Turnstile challenge token.
HTTP 404NOT_FOUND
The requested article slug, concept ID, or API route does not exist in the canonical knowledge repository.
Common TriggerQuerying /v1/articles/unknown-nonexistent-slug.
Recommended ResolutionCheck the slug spelling or query /v1/search to discover valid article slugs.
HTTP 429TOO_MANY_REQUESTS
Rate limit exceeded. The client has sent too many requests in a given amount of time.
Common TriggerExceeding 120 requests per minute from a single IP address.
Recommended ResolutionImplement exponential backoff or cache repeated GET responses locally.
HTTP 500INTERNAL_SERVER_ERROR
An unexpected error occurred within the Edge Worker runtime.
Common TriggerUnhandled runtime exception during graph traversal or index access.
Recommended ResolutionCheck the /api/status dashboard or report persistent issues to the engineering team.

Troubleshooting & Best Practices

  • Exponential Backoff: When encountering HTTP 429, pause execution for 1-2 seconds with exponential jitter before retrying.
  • Edge Caching: Take advantage of HTTP 200 responses with Cache-Control: public, s-maxage=86400 by caching locally in client memory or CDN layers.
  • URL Encoding: Always encode special characters and query strings using encodeURIComponent() in JavaScript or urllib.parse.quote() in Python.
  • Check Status: Visit the Status Dashboard to check live service uptime before reporting network issues.