Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wiseyield.co/llms.txt

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

WiseYield API errors share a consistent shape so integrations can handle them uniformly. The HTTP status code communicates the class of error; the code field gives the machine-readable kind; message is human-readable; details carries structured context when applicable.

​
Canonical response shape

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "message": "totalArea must be greater than 0",
  "details": {
    "totalArea": ["Total area must be greater than 0"]
  }
}
FieldAlways present?Notes
errorYesShort, human-readable category (Unauthorized, Validation failed, Not found, …)
codeWhen the error has a stable kindMachine-readable identifier — use this for switch statements
messageFrequentlyLonger human-readable description
detailsWhen structured context existsPer-field validation errors, available scopes, retry hints, etc.

​
Status code classes

StatusClassWhen
400Bad requestMalformed JSON, validation failed, business-rule violation
401UnauthorizedAuth missing, malformed, expired, or revoked
403ForbiddenAuthenticated but lacking the required scope, role, or whitelisted IP
404Not foundResource doesn’t exist or is soft-deleted
405Method not allowedHTTP method not implemented for this route
409ConflictUniqueness violation (e.g. duplicate farm name)
422UnprocessableSemantically valid request but cannot be fulfilled
429Too many requestsRate limit exceeded
5xxServer errorTransient — safe to retry with backoff

​
Error code reference

​
Authentication and authorization

codeStatusMeaning
MISSING_API_KEY401No Authorization header sent
INVALID_AUTH_FORMAT401Header is not Bearer <key>
INVALID_API_KEY_FORMAT401Key doesn’t match wy_(live|test)_[a-f0-9]{48}
INVALID_API_KEY401Key not found or revoked
INACTIVE_API_KEY401Key exists but is currently disabled
EXPIRED_API_KEY401Key passed its expiresAt timestamp
UNAUTHORIZED401Generic auth failure (session-auth surfaces)
IP_NOT_WHITELISTED403Request came from an IP not in the key’s allowlist
INSUFFICIENT_SCOPE403Key is valid but missing the scope this route requires
FORBIDDEN403Authenticated but not authorized for this resource
AUTH_ERROR500Auth subsystem failure — retry with backoff

​
Resource and validation

codeStatusMeaning
NOT_FOUND404Resource doesn’t exist or has been soft-deleted
VALIDATION_ERROR400Request body or query failed schema validation — see details
INVALID_ID400Path parameter (e.g. :id) is not a valid UUID
CONFLICT409Uniqueness or state-machine violation
LIMIT_EXCEEDED400A per-user limit (e.g. 10 API keys) was hit

​
Rate limiting

codeStatusMeaning
RATE_LIMIT_EXCEEDED429Per-user sliding-window limit reached. Response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (ISO 8601)

​
Server

codeStatusMeaning
INTERNAL_ERROR500Generic unexpected failure
SERVICE_UNAVAILABLE503Downstream dependency unavailable (e.g. AI provider, FX rate source) — fail-open behavior varies per route

​
Validation error details

For 400 VALIDATION_ERROR, details is an object whose keys are field names and whose values are arrays of human-readable messages: 
{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "name": ["Name is required"],
    "totalArea": ["Total area must be greater than 0"],
    "country": ["Country is required"]
  }
}
Top-level keys correspond to request body fields. Nested fields use dot-notation (boundaries.coordinates).

​
Insufficient-scope details

For 403 INSUFFICIENT_SCOPE, details tells you exactly what’s needed: 
{
  "error": "Forbidden",
  "code": "INSUFFICIENT_SCOPE",
  "message": "Insufficient permissions. Required scope: farms:write",
  "details": {
    "requiredScope": "farms:write",
    "availableScopes": ["farms:read", "crops:read"]
  }
}
Recreate the key with the missing scope, or rotate to a key that has it.

​
Retry strategy by status

StatusRetry?How
4xx (except 429)NoFix the request — retrying the same payload yields the same error
429YesWait until X-RateLimit-Reset (ISO 8601), then retry. See Rate-limit handling
5xxYesExponential backoff with jitter, max 3 attempts

​
See also