Error codes, response format, and handling - Yoshi API

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

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid, expired, or missing API key
`NOT_FOUND`	404	Resource doesn’t exist or you don’t have access
`VALIDATION_ERROR`	422	Invalid request parameters (check `param` field)
`RATE_LIMITED`	429	Too many requests (check `retry_after` field)
`INTERNAL_ERROR`	500	Something went wrong on our end

Error Fields

Field	Type	Description
`type`	`string`	Stable URI for this error type (inspired by RFC 9457)
`code`	`string`	Machine-readable error code for programmatic handling
`message`	`string`	Developer-facing explanation with details
`display_message`	`string \| null`	Safe to show to end users in a UI
`param`	`string \| null`	Which request parameter caused a validation error
`retry_after`	`number \| null`	Seconds 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']}")

const response = await fetch("https://api.yoshi.ai/accounts", {
  headers: { Authorization: "Bearer yoshi_YOUR_KEY" },
});

if (response.ok) {
  const { data } = await response.json();
} else {
  const { error } = await response.json();
  if (error.code === "RATE_LIMITED") {
    console.log(`Retry after ${error.retry_after} seconds`);
  } else {
    console.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