Troubleshooting and frequently asked questions

​

Authentication

​

401 Unauthorized

• Confirm your key starts with yoshi_
• Check that the Authorization header uses the Bearer scheme: Authorization: Bearer yoshi_YOUR_KEY
• Verify the key hasn’t been revoked in your dashboard
• Make sure there are no extra spaces or newlines in the key

# Correct
curl https://api.yoshi.ai/accounts \
  -H "Authorization: Bearer yoshi_3xK9mP..."

# Wrong — missing "Bearer"
curl https://api.yoshi.ai/accounts \
  -H "Authorization: yoshi_3xK9mP..."

​

Rate limiting

​

429 Too Many Requests

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712764800
Retry-After: 43

if (response.status === 429) {
  const retryAfter = Number(response.headers.get("Retry-After")) || 60;
  await new Promise((r) => setTimeout(r, retryAfter * 1000));
}

​

Webhooks

​

Not receiving events

• URL must be HTTPS. HTTP endpoints are rejected.
• Return 2xx within 15 seconds. If your handler times out, the event is marked as failed and retried.
• Check the portal. Open the self-service portal to see delivery attempts, response codes, and retry status.
• Check event filters. If you specified filter_types when creating the endpoint, only those events are delivered.

​

Signature verification failing

• Use the raw request body for verification, not a parsed JSON object. Parsing and re-serializing changes whitespace and key order, which breaks the signature.
• Verify the timestamp is within your tolerance window (default: 5 minutes).
• Make sure you’re using the correct signing secret for this endpoint.

​

Transactions

​

Duplicate transactions

​

Amount has unexpected sign

• On a credit card account, a purchase (outflow) has a positive amount
• On a checking account, a purchase (outflow) has a negative amount

// Display
const label = `${tx.cash_flow_direction === "outflow" ? "-" : "+"}$${tx.amount_absolute}`;

// Logic
if (tx.cash_flow_direction === "outflow" && tx.amount_absolute > 100) {
  // Large purchase
}

​

date_posted vs date_authorized

​

Data freshness

​

Stale data / as_of timestamp

• The institution may sync less frequently (some update once per business day)
• There may be a temporary connection issue

​

Missing recent transactions

1. It won’t appear until the next sync
2. It may appear as pending first
3. It settles as posted within 1–3 business days

​

Pagination

​

Cursor returns the same data

• Make sure you’re passing the cursor from the most recent response, not a cached cursor.
• Don’t store cursors between sessions — they’re designed for sequential traversal.
• If a cursor becomes invalid, the API returns 400. Restart pagination without a cursor.

​

Still stuck?

{
  "meta": {
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}