Errors
The response envelope every Fungies API endpoint returns, and what each HTTP status code means.
Every Fungies API response — success or failure — uses the same two-shape envelope. Read the HTTP status code first, then unwrap the body.
Response envelope
A successful call returns status: "success" and puts the result under data:
{
"status": "success",
"data": {
"order": {
"object": "order",
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
}A failed call returns status: "error" and a single human-readable message:
{
"status": "error",
"error": {
"message": "Order not found"
}
}error.message is written for humans and can be reworded at any time, so branch on the HTTP
status code, never on the message string. Log the message for debugging and support, but don't
parse it.
Status codes
| Status | Meaning | What to do |
|---|---|---|
200 OK | The request succeeded. | Read data. |
400 Bad Request | Input failed validation, or the request isn't valid for the resource's current state (for example, cancelling a payment that is no longer cancellable). | Fix the request. Retrying the same request will fail the same way. |
401 Unauthorized | The API key is missing, malformed, or invalid — including a write endpoint called without a valid secret key. Also returned for a test-mode key while the workspace hasn't set up test mode, and while the workspace the key belongs to is offline. GET /v0/portal/url also returns it for a portal link requested with a test-mode key (portal links are live-only), and while the customer portal is disabled for the workspace. | Check your keys — see Authentication. For a test key, switch to Test mode in the dashboard once. If they're right, the workspace may be offline: Workspace lifecycle covers what that means and how to bring it back. For the portal cases, use a live key, or enable the customer portal in Settings. |
404 Not Found | The resource doesn't exist, or isn't in your workspace. | Check the id. Archived records are hidden from most reads — see Pagination. |
409 Conflict | The request collides with a limit on your account. Today this is returned when creating a product would exceed your plan's product limit. | Upgrade the plan, or archive an existing product. |
422 Unprocessable Content | The request was well-formed but couldn't be fulfilled. Returned by POST /v0/tax/calculate when tax can't be determined for the location you supplied. | Check the country, state, and postal code you sent. |
429 Too Many Requests | You've hit a rate limit. | Back off and retry — see Rate limits. |
5xx | The request did not complete. Some are explicitly retryable and say so in the message. | Retry with backoff, following the guidance on Idempotency for writes. |
Authentication failures always return 401, never 403. A read endpoint called with only a public
key succeeds; a write endpoint called the same way returns 401. See
Authentication for the full key model.
Handling errors
A minimal client that gets this right:
const response = await fetch("https://api.fungies.io/v0/orders/list", {
headers: { "x-fngs-public-key": PUBLIC_KEY },
});
const body = await response.json();
if (!response.ok) {
// Branch on the status, not the message.
if (response.status === 429 || response.status >= 500) {
// Retryable — back off and try again.
throw new RetryableError(body.error.message, response.headers.get("x-request-id"));
}
throw new Error(`Fungies API ${response.status}: ${body.error.message}`);
}
return body.data.orders;Every response carries an x-request-id header. Log it alongside the error — quoting it in a
support request is the fastest way for us to find your call. See
Rate limits & request IDs.
Last updated