Errors

Error model

Korta uses a flat error shape:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "requestId": "req-123",
  "details": {}
}

• requestId is optional and returned when X-Request-Id is provided.
• details is optional.
• Validation errors usually include field-level data in details.

HTTP status mapping

Status	Meaning	When it happens
400	Bad Request	Request validation fails (invalid schema, invalid URL, invalid params).
401	Unauthorized	Missing/invalid token, invalid API key, unverified account, invalid credentials.
403	Forbidden	Authenticated user tries to modify/delete a link they do not own, or blocked CORS origin.
404	Not Found	Route not found, URL not found, user not found, invalid/expired verification token.
409	Conflict	Email already in use, short ID already in use.
429	Too Many Requests	Endpoint-specific limiter exceeded (per-IP window and limit).
500	Internal Server Error	Unhandled server-side failure.
503	Service Unavailable	Temporary dependency failure (for example, verification email provider unavailable during registration).

Troubleshooting by status

400

• Cause: Invalid body/query/params.
• Resolution: Validate payload against endpoint schema and retry.

401

• Cause: Missing or expired JWT, invalid API key, or unverified user.
• Resolution: Re-authenticate, verify email, regenerate API key if needed.

403

• Cause: Insufficient permissions (ownership) or CORS origin not allowed.
• Resolution: Ensure resource ownership and verify CORS_ORIGINS / FRONTEND_URL env values.

404

• Cause: Wrong path or resource does not exist.
• Resolution: Check endpoint URL, IDs, and token links.

409

• Cause: Unique conflict (email or shortId).
• Resolution: Use a different email/short ID.

429

• Cause: Too many requests from the same IP in time window.
• Resolution: Back off and retry later; respect endpoint-specific limits from Rate Limits.

500

• Cause: Unexpected backend error.
• Resolution: Check server logs and retry.

503

• Cause: A required external dependency is temporarily unavailable (for example SMTP provider when sending verification email).
• Resolution: Retry after a short delay and check provider status; no partial account is kept if registration email delivery fails.