API referenceAPIAvailable

Error Handling

Understand API error responses, status codes, and debugging headers.

Last reviewed July 13, 2026

The Vendo API uses standard HTTP status codes and a consistent JSON error shape.

Error Response Format


{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

Common Status Codes

Status	Description
`400`	Invalid request body or business-rule violation
`401`	Missing or invalid API key
`403`	API key lacks required scopes
`404`	Resource not found
`409`	Conflict
`429`	Rate limit exceeded
`500`	Internal server error

Common Error Codes

Code	Meaning
`UNAUTHORIZED`	Missing or invalid API key
`FORBIDDEN`	Valid key, but insufficient scopes
`VALIDATION_ERROR`	Request body failed validation
`BAD_REQUEST`	Request is structurally valid but not allowed in the current state
`NOT_FOUND`	Resource not found
`RATE_LIMIT_EXCEEDED`	Too many requests
`CONFLICT`	Resource conflict
`INTERNAL_ERROR`	Unexpected server error

Validation Errors


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "errors": [
        { "path": "schedule.frequencyUnit", "message": "Invalid enum value" }
      ]
    }
  }
}

Rate Limiting

Rate-limited responses include:


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709510445

And a response body similar to:


{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down your requests.",
    "details": {
      "retryAfter": 45
    }
  }
}

Internal Errors


{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred. Please try again later."
  }
}

Request IDs

Every response includes an X-Request-Id header. Include that value when you contact support.

Practical Handling Guidance

Retry 429 and 500 responses with backoff.
Treat 400, 401, 403, and 404 as non-retryable until the request or credentials are corrected.
Log the response body and X-Request-Id for support/debugging.