Haszno.comDocumentation
HUENOpen the demo ↗
API reference
View as Markdown

Errors and rate limits

Error response shape, all HTTP status codes the API deliberately returns, retry guidance, and per-path rate limits.

Error response shape

All API errors use the same JSON envelope:

{ "error": "Hungarian error message" }

The error field is a human-readable string.

API error messages are in Hungarian only, regardless of the Accept-Language header. This will change before general availability. See Conventions — Language for examples.

Do not parse the error string to decide how to retry or branch your code. Use the HTTP status code instead.

HTTP status codes

The table below lists every HTTP status the API deliberately returns and what your client should do.

Status When What to do
200 Success. Read the response body.
201 Resource created (POST endpoints that create records). The new resource id is in the response body.
400 Invalid or malformed request: missing required field, type mismatch, out-of-range value, or invalid JSON. Fix the request; do not retry unchanged.
401 Missing credentials, or the credentials provided are invalid. Check your Authorization header or Basic auth config.
403 Authenticated but not permitted. Example: a state-changing request failed the CSRF origin check. Do not retry without fixing the request origin or authentication context.
404 Unknown path or resource ID not found. Verify the path and ID; do not retry.
405 HTTP method not supported on this path. Use the correct method; do not retry.
409 Conflict — the operation cannot proceed in the current state. Example: POST /api/webhooks/order with an out-of-stock SKU. Error body includes the specific SKU: "Elfogyott: DEMO-5". Fix the conflicting condition (e.g. check stock), then retry.
413 Request body exceeds the size limit (1 MB default; 10 MB for POST /api/feeds/import). Reduce the payload size; do not retry unchanged.
423 Resource locked. Retry after the lock is released.
429 Rate limit exceeded. Wait at least 60 seconds and retry. See Rate limits.
500 Unexpected server error. Retry up to 3 times with exponential back-off (1 s, 2 s, 4 s). Report persisting errors to the Haszno team.
503 Upstream dependency unavailable (e.g. the AI service required by POST /api/products/:id/ai-description). Retry with back-off; this is typically transient.

Retry guidance

Safe to retry

  • GET requests on 5xx: retry up to 3 times with exponential back-off (1 s → 2 s → 4 s).
  • 429 responses: wait at least 60 seconds before retrying.

Not safe to retry blindly

Write operations (POST, PUT, PATCH, DELETE) on 5xx responses may have partially succeeded server-side. Before retrying:

  1. Check the current resource state with the matching GET.
  2. Use the batchId returned by haszno_proposals_approve / POST /api/proposals/approve to roll back an approved batch if needed.

POST /api/products/apply-prices and POST /api/proposals/approve return a batchId or applied count. Record these values before retrying to avoid applying prices twice.

Never retry

Do not retry 400, 401, 403, 404, 405, or 409 responses. The error will recur until you fix the request.

Rate limits

Rate limits are per-instance on the hosted Vercel deployment. Because serverless function invocations may land on different cold-start instances, counters are not shared across instances. The effective per-IP budget may be higher than the figures below in practice. For self-hosted deployments, counts are shared within a single process.

Limits are enforced per client IP. The window for all general write limits is 60 seconds.

General write limits

Matching is by path prefix; the first matching rule wins.

Method Path prefix Limit per 60 s
POST /api/billing/plan 5
POST /api/shop-connections 10
POST /api/support/conversations 20
PUT /api/support/conversations 10
POST /api/partners/apply 10
POST /api/feeds/import 20
POST, PUT, PATCH All other paths 200
DELETE All paths 100

GET requests have no published rate limit. Avoid polling faster than once per minute; use a local cache for background polling.

Authentication limits

These limits are separate and use different windows.

Endpoint Limit
POST /api/auth/register 5 per IP per hour
POST /api/auth/login (by IP) 30 per IP per 15 minutes
POST /api/auth/login (by email) 10 per email address per 15 minutes — fail-closed: further login attempts for that email return 429 even with the correct password until the window expires

Rate limit response

{ "error": "Túl sok kérés — próbáld újra egy perc múlva." }

HTTP status: 429. The message translates to: "Too many requests — try again in a minute."

The authentication limits return 429 with a different message: "Túl sok próbálkozás. Próbáld újra néhány perc múlva." ("Too many attempts. Try again in a few minutes.").