Skip to main content

​
Error Response Format

All errors follow a consistent envelope: 
{
  "error": {
    "type": "https://api.yoshi.ai/errors/not-found",
    "code": "NOT_FOUND",
    "message": "The requested resource was not found.",
    "display_message": "We couldn't find what you're looking for.",
    "param": null,
    "retry_after": null
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-10T12:00:00Z"
  }
}

​
Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid, expired, or missing API key
NOT_FOUND404Resource doesn’t exist or you don’t have access
VALIDATION_ERROR422Invalid request parameters (check param field)
RATE_LIMITED429Too many requests (check retry_after field)
INTERNAL_ERROR500Something went wrong on our end

​
Error Fields

FieldTypeDescription
typestringStable URI for this error type (inspired by RFC 9457)
codestringMachine-readable error code for programmatic handling
messagestringDeveloper-facing explanation with details
display_messagestring | nullSafe to show to end users in a UI
paramstring | nullWhich request parameter caused a validation error
retry_afternumber | nullSeconds until you can retry (only on RATE_LIMITED)

​
Handling Errors

import httpx

response = httpx.get(
    "https://api.yoshi.ai/accounts",
    headers={"Authorization": "Bearer yoshi_YOUR_KEY"},
)

if response.status_code == 200:
    data = response.json()["data"]
elif response.status_code == 429:
    error = response.json()["error"]
    retry_after = error["retry_after"]
    print(f"Rate limited. Retry after {retry_after} seconds.")
elif response.status_code == 401:
    print("Invalid API key.")
else:
    error = response.json()["error"]
    print(f"Error: {error['code']} - {error['message']}")

​
Request IDs

Every response includes a request_id in the meta object and as an X-Request-Id response header. Include this when contacting support about a specific request. 
curl -v https://api.yoshi.ai/accounts \
  -H "Authorization: Bearer yoshi_YOUR_KEY" 2>&1 | grep X-Request-Id
# < X-Request-Id: req_a1b2c3d4-e5f6-7890-abcd-ef1234567890
Last modified on April 14, 2026