Skip to content

Internal Server Error

URI: https://docs.ankatech.co/errors/internal
HTTP Status: 500 Internal Server Error

When you see this

The server encountered an unexpected condition or unhandled exception while processing a valid request. This is the generic fallback for errors not covered by more specific handlers.

A 500 is a fault of the service that answered, never a verdict about your request. Its detail is a fixed sentence (for example An unexpected error occurred.) that names nothing about the fault: the exception's own text is written to the service log and never returned. Among the faults answered this way rather than as a client error:

  • Admin API: an unexpected fault while creating a key (POST /api/v3/admin/tenants/{tenantId}/keys), where the key may or may not exist, so read it back before retrying; and an unexpected fault during a deployment-policy dry run (PUT /api/v3/admin/platform/deployment/policies?dryRun=true), which is not reported as a validation finding.
  • Auth API: an unanticipated fault during a token exchange, which is not an invalid_grant, and a constraint violation on an object the service built itself.
  • Audit API: an internal inconsistency the service detected itself; a refusal of what you sent stays a 400.

An unreachable or timed-out upstream is not this type: it keeps its own status (502, 504).

Common Causes

  • Unhandled exceptions in business logic or controller code.
  • Null-pointer, type-conversion, or configuration errors at runtime.
  • Failures in downstream services or external dependencies (DB, keystore, third-party APIs).
  • Serialization/deserialization problems or unexpected I/O errors.

How to Resolve

  1. Note the request's correlation identifier (extensions.requestId or the top-level correlationId, by service): the detail carries no diagnostic, and the identifier locates the logged fault.
  2. Retry the request after a brief pause—transient infrastructure or dependency issues may self-heal.
  3. If the error persists, check your server logs and health dashboards for stack traces or dependency failures.
  4. Contact AnkaTech support with the request ID, timestamp, and any relevant log excerpts.

If you continue to receive a 500 error after these steps, please consult the full Developer Hub Reference or reach out to support.