Application error reference

Why it happens

The JWT authenticator decodes the token before the firewall creates a token storage entry. Any structural or cryptographic failure aborts authentication and the entry point converts the AuthenticationException into a 401 response.

Common causes

• Token was signed with a key pair that no longer matches JWT_PUBLIC_KEY (key rotated, or dev keys used against prod).
• Token string was truncated, URL-encoded twice, or wrapped in quotes by the client.
• The header used a scheme other than Bearer, so the raw value was parsed as a token.
• The payload was hand-crafted in a test and is missing the configured user identity claim.

How to fix it

1. 1

   Verify the key pair the application actually loaded

   Compare the fingerprint of the private key that issued the token with the public key resolved at runtime. A passphrase mismatch fails the same way as a wrong key.

   php bin/console lexik:jwt:check-config
   php bin/console debug:config lexik_jwt_authentication

2. 2

   Confirm the header shape on the client

   The scheme is case sensitive and a single space separates it from the token.

   Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

3. 3

   Inspect the decode failure reason instead of guessing

   JWTDecodeFailureException exposes a reason constant. Log it in the failure handler so invalid-signature is never confused with expired.

   use Lexik\Bundle\JWTAuthenticationBundle\Exception\JWTDecodeFailureException;
   
   if ($exception instanceof JWTDecodeFailureException) {
       $this->logger->warning('JWT decode failed', [
           'reason' => $exception->getReason(), // invalid_token | unverified_token | expired_token
       ]);
   }

Related exceptions

• Lexik\Bundle\JWTAuthenticationBundle\Exception\JWTDecodeFailureException
• Lexik\Bundle\JWTAuthenticationBundle\Exception\InvalidTokenException
• Symfony\Component\Security\Core\Exception\AuthenticationException

Related services & controllers

Notes for developers

Why it happens

Access tokens are deliberately short lived. The decoder throws before the user provider is queried, so no database round trip happens.

Common causes

• Normal token lifetime elapsed and the client did not refresh.
• Client and server clocks drift by more than the configured leeway.
• A long-running background job reused a token captured at boot.

How to fix it

1. 1

   Refresh, then replay the original request once

   This is the only 401 the client should retry automatically. Exchange the refresh token and repeat the call a single time to avoid loops.

   POST /api/v1/token/refresh HTTP/1.1
   Content-Type: application/json
   
   {"refresh_token": "e9c1...f0"}

2. 2

   Distinguish expiry from invalidity on the client

   Branch on the code member, never on the status. Both expiry and invalid signature return 401.

   if (res.status === 401 && body.code === "AUTH_TOKEN_EXPIRED") {
     await refresh()
     return retryOnce(request)
   }

3. 3

   Keep clocks in sync for machine-to-machine callers

   Enable NTP on worker hosts; a two minute drift makes freshly minted tokens look expired.

Related exceptions

• Lexik\Bundle\JWTAuthenticationBundle\Exception\ExpiredTokenException
• Symfony\Component\Security\Core\Exception\AuthenticationExpiredException

Related services & controllers

Notes for developers

Why it happens

When no authenticator supports the request, the firewall delegates to its entry point, which returns 401 rather than redirecting for stateless APIs.

Common causes

• The client dropped the header on a redirect or on a cross-origin preflight follow-up.
• A reverse proxy stripped Authorization before forwarding.
• The route was assumed public but is matched by the api firewall pattern.
• Cookie-based session expired and the SPA kept calling protected endpoints.

How to fix it

1. 1

   Check whether the route is genuinely meant to be public

   php bin/console debug:router api_health
   php bin/console debug:firewall api

2. 2

   Allow the header through the proxy

   Nginx and some CDNs drop unknown headers on internal redirects.

   proxy_set_header Authorization $http_authorization;
   proxy_pass_header Authorization;

3. 3

   Mark truly public endpoints explicitly

   security:
     access_control:
       - { path: ^/api/v1/health$, roles: PUBLIC_ACCESS }
       - { path: ^/api,           roles: IS_AUTHENTICATED_FULLY }

Related exceptions

• Lexik\Bundle\JWTAuthenticationBundle\Exception\MissingTokenException
• Symfony\Component\Security\Core\Exception\AuthenticationCredentialsNotFoundException

Related services & controllers

Notes for developers

Why it happens

The password hasher compares the submitted secret against the stored hash. On mismatch, and also when the identifier does not exist, a BadCredentialsException is thrown so the two cases are indistinguishable to the caller.

Common causes

• Wrong password, or an identifier that does not exist.
• User rows were imported without rehashing, so the stored value is not in the configured algorithm.
• The login payload used different field names than the authenticator expects.
• Password contained characters mangled by a client that did not send UTF-8.

How to fix it

1. 1

   Confirm the payload keys the authenticator reads

   {
     "email": "dev@example.com",
     "password": "correct horse battery staple"
   }

2. 2

   Check the stored hash algorithm

   Imported bcrypt hashes will not verify under a sodium-only configuration without a migrate_from entry.

   security:
     password_hashers:
       App\Entity\User:
         algorithm: auto
         migrate_from: ["bcrypt"]

3. 3

   Keep the response deliberately vague

   Do not tell the client which half was wrong. User enumeration is the reason UserNotFoundException is folded into this error.

Related exceptions

• Symfony\Component\Security\Core\Exception\BadCredentialsException
• Symfony\Component\Security\Core\Exception\UserNotFoundException
• Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException

Related services & controllers

Notes for developers

Why it happens

The repository returned null and the controller raised a domain not-found exception. This is distinct from the authentication path, where a missing user is reported as bad credentials.

Common causes

• The identifier belongs to a soft-deleted or anonymised account.
• A stale client cache still holds an id from a purged environment.
• The caller is scoped to a tenant that does not own the record, and the query filter hid it.
• A user provider still references an id whose row was removed while a session was live.

How to fix it

1. 1

   Query with the tenant filter in mind

   A Doctrine filter can make a row invisible; that surfaces as not found rather than forbidden. Disable the filter only in admin contexts.

   $user = $this->users->find($id)
       ?? throw new UserNotFoundDomainException($id);

2. 2

   Treat soft-deleted accounts explicitly

   Return 410 Gone instead if the product needs to distinguish deleted from never-existed.

3. 3

   Invalidate sessions when a user is removed

   php bin/console app:sessions:invalidate --user=42

Related exceptions

• App\Domain\Exception\UserNotFoundDomainException
• Symfony\Component\Security\Core\Exception\UserNotFoundException
• Doctrine\ORM\EntityNotFoundException

Related services & controllers

Why it happens

User checkers run after the credentials are validated, during checkPostAuth. They throw an AccountStatusException subclass, which the failure handler renders as 403 because the identity is known.

Common causes

• An administrator deactivated the account.
• Automatic lockout after repeated failed logins.
• Email or phone verification never completed.
• The subscription lapsed and a checker gates access on billing state.

How to fix it

1. 1

   Read the reason from your user checker, not from the status

   public function checkPostAuth(UserInterface $user): void
   {
       if (!$user->isVerified()) {
           throw new AccountNotVerifiedException();
       }
   
       if ($user->isLocked()) {
           throw new LockedException();
       }
   }

2. 2

   Give the client an actionable next step

   Include a resend-verification or contact-support hint in detail so the UI can render the right recovery path.

3. 3

   Reactivate from the console when appropriate

   php bin/console app:user:enable dev@example.com

Related exceptions

• Symfony\Component\Security\Core\Exception\DisabledException
• Symfony\Component\Security\Core\Exception\LockedException
• Symfony\Component\Security\Core\Exception\AccountExpiredException
• App\Security\Exception\AccountNotVerifiedException

Related services & controllers

Notes for developers

Why it happens

Refresh tokens are single use. On exchange the old record is deleted and a new one is issued. Replaying the old value therefore finds nothing, which is treated as a possible token theft signal.

Common causes

• Two tabs or two threads refreshed concurrently and one lost the race.
• The user logged out, changed password, or an admin revoked all sessions.
• The token exceeded its absolute lifetime.
• A stolen token was replayed after the legitimate client already rotated it.

How to fix it

1. 1

   Serialise refresh calls in the client

   Share one in-flight refresh promise across callers so parallel requests cannot double-spend the token.

   let inflight: Promise<Session> | null = null
   
   export function refresh() {
     inflight ??= doRefresh().finally(() => {
       inflight = null
     })
     return inflight
   }

2. 2

   Send the user back to login without retrying

   This error is terminal. Clear the local session and stop; retrying only produces more 401s.

3. 3

   Alert on reuse of an already-rotated token

   Reuse after successful rotation is the classic theft indicator. Revoke the whole family for that user.

   php bin/console app:refresh-token:revoke --user=42 --all

Related exceptions

• App\Security\Exception\RefreshTokenRevokedException
• Gesdinet\JWTRefreshTokenBundle\Exception\InvalidRefreshTokenException

Related services & controllers

Notes for developers

Why it happens

MapRequestPayload validates the DTO after denormalisation and throws a ValidationFailedException, which the kernel converts to 422 with the violation list preserved.

Common causes

• A required field was empty, or a value fell outside its allowed range.
• A nested collection item failed while the parent looked fine.
• Client and server disagree on the version of the schema.
• A Valid cascade was forgotten, so nested violations appear only after a later save.

How to fix it

1. 1

   Read the errors array, not just detail

   Each entry carries a property path that maps one-to-one onto a form field.

   for (const v of body.errors ?? []) {
     setFieldError(v.field, v.message)
   }

2. 2

   Keep constraints on the DTO, not the entity, for inbound payloads

   final class CreateOrderRequest
   {
       public function __construct(
           #[Assert\NotBlank]
           #[Assert\Uuid]
           public string $customerId,
   
           #[Assert\Count(min: 1, max: 50)]
           #[Assert\Valid]
           public array $lines = [],
       ) {}
   }

3. 3

   Reproduce quickly against the validator

   php bin/console debug:validator "App\\Dto\\CreateOrderRequest"

Related exceptions

• Symfony\Component\Validator\Exception\ValidationFailedException
• Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException

Related services & controllers

Notes for developers

Why it happens

The serializer throws before validation runs, so there is no violation list to report; only the syntax or type error is known.

Common causes

• Trailing comma, single quotes, or an unescaped newline in the JSON.
• A string was sent where the DTO declares int, and the property is not nullable.
• The body was gzipped or form-encoded while the header claimed JSON.
• An empty body on a route that requires a payload.

How to fix it

1. 1

   Validate the payload locally before blaming the API

   jq . payload.json > /dev/null && echo "valid JSON"

2. 2

   Send types that match the DTO declaration

   { "quantity": 3, "priceCents": 1999 }

3. 3

   Return the decoder message without leaking internals

   if ($e instanceof NotEncodableValueException) {
       throw new BadRequestHttpException('Request body is not valid JSON.', $e);
   }

Related exceptions

• Symfony\Component\Serializer\Exception\NotEncodableValueException
• Symfony\Component\Serializer\Exception\NotNormalizableValueException
• Symfony\Component\HttpKernel\Exception\BadRequestHttpException

Related services & controllers

Why it happens

MapQueryParameter and MapQueryString reject the request before the controller body executes when a non-nullable parameter has no value.

Common causes

• Pagination or filter parameter omitted on a route that requires it.
• An empty string was sent, which is not the same as absent for typed parameters.
• Array-style parameters were sent with the wrong bracket syntax.
• The client built the URL from a template and left a placeholder unreplaced.

How to fix it

1. 1

   Give parameters defaults when they are genuinely optional

   #[Route('/api/v1/orders', methods: ['GET'])]
   public function list(
       #[MapQueryParameter] int $page = 1,
       #[MapQueryParameter] int $perPage = 25,
       #[MapQueryParameter] string $status = 'any',
   ): JsonResponse {

2. 2

   Name the missing parameter in the response

   Reuse the errors array with a field entry so the client can point at the exact input.

3. 3

   Inspect what the route expects

   php bin/console debug:router order_list -v

Related exceptions

• Symfony\Component\HttpKernel\Exception\BadRequestHttpException
• Symfony\Component\HttpKernel\Exception\NotFoundHttpException

Related services & controllers

Why it happens

The payload mapper picks a decoder from Content-Type. With no matching decoder it refuses the request rather than guessing the format.

Common causes

• Content-Type omitted entirely, so the body was treated as form data.
• A file was posted as raw binary to a route expecting multipart/form-data.
• A charset suffix or vendor media type the endpoint does not declare.
• An HTML form posted to a JSON-only endpoint.

How to fix it

1. 1

   Always set Content-Type explicitly

   curl -X POST https://api.example.com/api/v1/orders \
     -H "Content-Type: application/json" \
     -d '{"customerId":"9c1f..."}'

2. 2

   Declare accepted formats on the route

   #[Route('/api/v1/orders', methods: ['POST'], format: 'json')]

3. 3

   Use multipart for uploads

   Send the file part plus a JSON metadata part rather than encoding the file inside JSON.

Related exceptions

• Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException

Related services & controllers

Why it happens

IsGranted or a manual denyAccessUnlessGranted call triggers the voters. If none grants access, an AccessDeniedException is thrown and the firewall renders 403.

Common causes

• The required role is absent from the token.
• A voter returned abstain for every voter, and the strategy denies by default.
• Roles changed in the database but the caller still holds an old token.
• The attribute string in IsGranted does not match what the voter supports.

How to fix it

1. 1

   Ask the decision manager what happened

   The profiler security panel lists every voter and its vote for the request.

   php bin/console debug:container security.access.decision_manager

2. 2

   Make voter support explicit

   protected function supports(string $attribute, mixed $subject): bool
   {
       return \in_array($attribute, ['ORDER_VIEW', 'ORDER_CANCEL'], true)
           && $subject instanceof Order;
   }

3. 3

   Reissue the token after a role change

   Roles are baked into the JWT payload. Force a refresh so new roles take effect.

Related exceptions

• Symfony\Component\Security\Core\Exception\AccessDeniedException
• Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException

Related services & controllers

Notes for developers

Why it happens

Role checks are resolved by RoleHierarchyVoter. Only roles reachable from those on the token count, so a missing hierarchy edge fails the check even when the intent was to allow it.

Common causes

• role_hierarchy is missing an edge, for example ROLE_MANAGER does not include ROLE_SUPPORT.
• The role was granted on the user entity but not exposed by getRoles.
• Environment drift: the hierarchy differs between staging and production.
• A typo in the role constant, such as ROLE_ADMINISTRATOR versus ROLE_ADMIN.

How to fix it

1. 1

   Model the hierarchy once, in config

   security:
     role_hierarchy:
       ROLE_SUPPORT: [ROLE_USER]
       ROLE_MANAGER: [ROLE_SUPPORT]
       ROLE_ADMIN:   [ROLE_MANAGER]

2. 2

   Inspect the effective roles of the token

   php bin/console app:user:roles dev@example.com --effective

3. 3

   Reference roles through constants

   #[IsGranted(Roles::MANAGER)]
   final class AdminReportController { }

Related exceptions

• Symfony\Component\Security\Core\Exception\AccessDeniedException

Related services & controllers

Why it happens

Role checks are coarse. A voter comparing the subject owner with the current user provides the fine-grained decision, and denies when they differ.

Common causes

• An identifier from another tenant was guessed or leaked into a client cache.
• The controller checked the role but forgot the object-level voter.
• A support agent impersonated a user without the impersonation attribute.
• A shared resource was moved to another workspace.

How to fix it

1. 1

   Always pass the subject to the authorization check

   #[Route('/api/v1/orders/{id}', methods: ['GET'])]
   #[IsGranted('ORDER_VIEW', subject: 'order')]
   public function show(Order $order): JsonResponse
   {
       return $this->json($this->presenter->present($order));
   }

2. 2

   Decide deliberately between 403 and 404

   403 confirms the record exists. If existence itself is confidential, answer 404 instead and document that choice per endpoint.

3. 3

   Enforce tenancy at the query layer as a second line of defence

   $qb->andWhere('o.tenant = :tenant')
      ->setParameter('tenant', $this->tenantContext->current());

Related exceptions

• Symfony\Component\Security\Core\Exception\AccessDeniedException
• App\Domain\Exception\TenantMismatchException

Related services & controllers

Notes for developers

Why it happens

The CSRF manager compares the submitted token with the one stored in the session. A missing session, a rotated token, or a cross-site submission all fail the comparison.

Common causes

• The form page was cached and its token expired with the session.
• The session cookie was blocked by SameSite rules during a cross-site post.
• The token field was renamed, or the form was rebuilt client side without it.
• CSRF protection is enabled on an endpoint that is actually stateless and token-authenticated.

How to fix it

1. 1

   Render the token with the form

   <form method="post">
     <input type="hidden" name="_token" value="{{ csrf_token('delete_item') }}">
   </form>

2. 2

   Do not enable CSRF on stateless JSON APIs

   Bearer-token endpoints are not vulnerable to classic CSRF; leave the firewall stateless and skip the check.

   security:
     firewalls:
       api:
         stateless: true

3. 3

   Avoid caching pages that embed tokens

   Send Cache-Control: private, no-store on any HTML containing a CSRF token.

Related exceptions

• Symfony\Component\Security\Csrf\Exception\InvalidCsrfTokenException
• Symfony\Component\Form\Exception\InvalidCsrfTokenException

Related services & controllers

Why it happens

The workflow component blocks transitions whose guards or from-places do not match. The domain service converts that block into a conflict rather than a server error.

Common causes

• The client acted on stale data and the entity already moved on.
• Two operators acted on the same record at once.
• A guard expression depends on data that is not set yet.
• The workflow definition omits the transition the product expects.

How to fix it

1. 1

   Ask the workflow before acting

   if (!$this->workflow->can($order, 'ship')) {
       throw new InvalidStateTransitionException($order->getStatus(), 'ship');
   }
   
   $this->workflow->apply($order, 'ship');

2. 2

   Expose the allowed transitions in the resource representation

   Let the UI hide impossible actions instead of discovering them through 409s.

   { "id": "8f21", "status": "paid", "allowedTransitions": ["ship", "refund"] }

3. 3

   Visualise the definition when debugging

   php bin/console workflow:dump order | dot -Tpng -o order.png

Related exceptions

• App\Domain\Exception\InvalidStateTransitionException
• Symfony\Component\Workflow\Exception\NotEnabledTransitionException
• Symfony\Component\Workflow\Exception\UndefinedTransitionException

Related services & controllers

Notes for developers

Why it happens

The payment service checks the aggregate before contacting the provider so a duplicate submission cannot create a second charge.

Common causes

• The user double-clicked, or the client retried after a timeout that had actually succeeded.
• A provider webhook marked the order paid before the synchronous response returned.
• A replayed webhook without idempotency handling.
• Manual reconciliation marked the order paid out of band.

How to fix it

1. 1

   Send an idempotency key with every payment attempt

   POST /api/v1/orders/8f21/pay HTTP/1.1
   Idempotency-Key: 4f1c9b2e-7d3a-4a91-9c6e-0b2f8d7a1c33

2. 2

   Treat this as success in the client

   The desired end state is already reached. Show the receipt instead of an error dialog.

3. 3

   Guard inside the transaction

   $order = $this->orders->findForUpdate($id);
   
   if ($order->isPaid()) {
       throw new OrderAlreadyPaidException($order->getId());
   }

Related exceptions

• App\Domain\Exception\OrderAlreadyPaidException
• App\Domain\Exception\DomainConflictException

Related services & controllers

Why it happens

Reservation happens inside a transaction with a row lock. If available stock is below the requested amount the whole reservation is rolled back, so an order is never partially reserved.

Common causes

• Another customer reserved the remaining units first.
• A stock sync from the warehouse lowered the figure after the page was rendered.
• Reserved-but-unconfirmed carts are holding inventory that has not expired yet.
• The catalogue read model is cached and shows a stale availability figure.

How to fix it

1. 1

   Return per-line availability so the cart can self-correct

   {
     "errors": [
       { "field": "lines[0].quantity", "message": "Only 2 units available.", "code": "STOCK_INSUFFICIENT", "meta": { "requested": 5, "available": 2 } }
     ]
   }

2. 2

   Lock the row, do not read then write

   $this->em->wrapInTransaction(function () use ($sku, $qty): void {
       $item = $this->inventory->findOneBySkuForUpdate($sku);
   
       if ($item->available() < $qty) {
           throw new InsufficientStockException($sku, $qty, $item->available());
       }
   
       $item->reserve($qty);
   });

3. 3

   Expire abandoned reservations

   A scheduled release job keeps phantom shortages from accumulating.

Related exceptions

• App\Domain\Exception\InsufficientStockException
• Doctrine\DBAL\Exception\LockWaitTimeoutException

Related services & controllers

Notes for developers

Why it happens

A quota guard runs before the write. It compares current usage with the plan entitlement and rejects the operation with a payment-required status so the client can route the user to billing.

Common causes

• The plan entitlement is genuinely exhausted.
• Usage counters were not decremented when resources were deleted.
• A downgrade took effect while usage exceeded the lower tier.
• Trial expired and entitlements fell back to the free tier.

How to fix it

1. 1

   Report usage and the upgrade path

   { "meta": { "limit": 5, "used": 5, "resource": "projects", "upgradeUrl": "/billing/plans" } }

2. 2

   Check quota in one place

   $this->quota->assertWithin('projects', $account)
       ?: throw new PlanLimitReachedException('projects', $limit);

3. 3

   Recompute counters after bulk deletions

   php bin/console app:quota:recalculate --account=42

Related exceptions

• App\Domain\Exception\PlanLimitReachedException
• App\Billing\Exception\EntitlementException

Related services & controllers

Notes for developers

Why it happens

Application-level uniqueness checks are racy. The database index is the real guarantee, so a duplicate that slips past validation surfaces here and is translated into a 409.

Common causes

• Two concurrent requests passed the UniqueEntity check before either committed.
• A retried request created the row twice because the endpoint is not idempotent.
• An import job did not deduplicate its input.
• Case sensitivity differs between the validator and the collation of the index.

How to fix it

1. 1

   Keep the validator for messaging and the index for correctness

   #[ORM\Entity]
   #[ORM\UniqueConstraint(name: 'uniq_user_email', columns: ['email'])]
   #[UniqueEntity(fields: ['email'], message: 'This email is already registered.')]
   class User { }

2. 2

   Translate the DBAL exception into a domain conflict

   use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
   
   try {
       $this->em->flush();
   } catch (UniqueConstraintViolationException $e) {
       throw new ResourceAlreadyExistsException('user.email', $e);
   }

3. 3

   Make creation idempotent where duplicates are expected

   An upsert keyed on a natural identifier removes the error class entirely for importers and webhooks.

Related exceptions

• Doctrine\DBAL\Exception\UniqueConstraintViolationException
• App\Domain\Exception\ResourceAlreadyExistsException

Related services & controllers

Notes for developers

Why it happens

Referential integrity is enforced by the database. Doctrine surfaces the driver error, which is translated into a conflict describing the blocking relation.

Common causes

• Deleting a category that still has products.
• Inserting a child with an id whose parent was removed concurrently.
• Cascade rules configured in the ORM but not in the schema, or the reverse.
• Fixtures loaded in the wrong order.

How to fix it

1. 1

   Decide the deletion policy explicitly

   #[ORM\ManyToOne(inversedBy: 'products')]
   #[ORM\JoinColumn(nullable: false, onDelete: 'RESTRICT')]
   private Category $category;

2. 2

   Offer a soft alternative in the API

   Archiving instead of deleting usually matches user intent and avoids the conflict altogether.

3. 3

   Tell the client what blocks the delete

   { "meta": { "blockedBy": "products", "count": 14 } }

Related exceptions

• Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException
• Doctrine\DBAL\Exception\NotNullConstraintViolationException

Related services & controllers

Why it happens

Route parameter converters and repository lookups throw when nothing matches, which the kernel renders as 404. Proxy initialisation failures indicate the row vanished after the reference was loaded.

Common causes

• The id is wrong, or belongs to another environment.
• The row was deleted between two requests.
• A Doctrine filter hides the row from the current context.
• A stale relation still points at a deleted parent, so the proxy cannot load.

How to fix it

1. 1

   Prefer explicit lookups over silent nulls

   $order = $this->orders->find($id)
       ?? throw new NotFoundHttpException(\sprintf('Order %s not found.', $id));

2. 2

   Check for orphaned references

   php bin/console doctrine:schema:validate

3. 3

   Keep the message generic in production

   Do not echo internal identifiers or table names in the public detail string.

Related exceptions

• Doctrine\ORM\EntityNotFoundException
• Doctrine\ORM\NoResultException
• Symfony\Component\HttpKernel\Exception\NotFoundHttpException

Related services & controllers

Why it happens

A Version column is compared during flush. When the stored version no longer matches the one loaded, Doctrine aborts to prevent a lost update.

Common causes

• Two users edited the same record simultaneously.
• A background job wrote to the entity while a request held an older copy.
• The client omitted or hardcoded the version field.
• A long-lived form was submitted much later than it was rendered.

How to fix it

1. 1

   Version the entity and require the version on write

   #[ORM\Version]
   #[ORM\Column(type: 'integer')]
   private int $version = 1;

2. 2

   Reload, re-apply, retry once

   try {
       $this->em->flush();
   } catch (OptimisticLockException) {
       $this->em->refresh($order);
       $this->applyChanges($order, $command);
       $this->em->flush();
   }

3. 3

   Surface a merge prompt in the UI

   For human-facing edits, show what changed rather than silently overwriting the other person's work.

Related exceptions

• Doctrine\ORM\OptimisticLockException
• Doctrine\ORM\PessimisticLockException

Related services & controllers

Notes for developers

Why it happens

These are infrastructure failures. The exception subscriber deliberately hides driver detail and answers 503 with a Retry-After hint so callers back off instead of hammering a struggling database.

Common causes

• Credentials or DATABASE_URL wrong after a deploy or secret rotation.
• Connection limit reached because workers or PHP-FPM children outnumber available slots.
• Failover or maintenance window on the managed instance.
• Deadlock or lock wait timeout under write contention.

How to fix it

1. 1

   Verify connectivity from the application host

   php bin/console dbal:run-sql "SELECT 1"
   php bin/console debug:config doctrine dbal

2. 2

   Size the pool against the real worker count

   Web workers plus Messenger consumers plus cron all draw from the same limit. Cap consumers before raising server limits.

3. 3

   Retry deadlocks in the transaction boundary, not in the controller

   use Doctrine\DBAL\Exception\DeadlockException;
   
   for ($attempt = 1; $attempt <= 3; $attempt++) {
       try {
           return $this->em->wrapInTransaction($work);
       } catch (DeadlockException) {
           usleep(50_000 * $attempt);
       }
   }
   
   throw new DatabaseUnavailableException('Deadlock retries exhausted.');

Related exceptions

• Doctrine\DBAL\Exception\ConnectionException
• Doctrine\DBAL\Exception\ConnectionLost
• Doctrine\DBAL\Exception\DeadlockException
• Doctrine\DBAL\Exception\LockWaitTimeoutException

Related services & controllers

Notes for developers

Why it happens

HttpClient enforces separate connect and total timeouts. Exceeding either aborts the transfer, and the gateway returns 504 to keep the caller's own timeout budget intact.

Common causes

• The upstream is degraded or overloaded.
• Timeouts are set higher than the caller's own budget, so failures cascade.
• DNS or TLS negotiation is slow from the application network.
• A large payload was requested without pagination.

How to fix it

1. 1

   Set explicit, tight timeouts per client

   framework:
     http_client:
       scoped_clients:
         billing.client:
           base_uri: 'https://billing.example.com'
           timeout: 3
           max_duration: 8

2. 2

   Retry idempotent calls with jittered backoff only

   framework:
     http_client:
       scoped_clients:
         billing.client:
           retry_failed:
             max_retries: 2
             delay: 250
             multiplier: 2
             jitter: 0.2

3. 3

   Move slow work off the request path

   Dispatch a Messenger message and let the client poll, rather than holding an HTTP connection open.

Related exceptions

• Symfony\Component\HttpClient\Exception\TimeoutException
• Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface

Related services & controllers

Notes for developers

Why it happens

A ServerException from the upstream is not the caller's fault, so it is reported as a bad gateway rather than propagating the upstream status verbatim.

Common causes

• The upstream is deploying or has an internal fault.
• A proxy in between returned an HTML error page instead of JSON.
• TLS verification failed because of an expired or mismatched certificate.
• The upstream changed its response schema.

How to fix it

1. 1

   Fail fast with a circuit breaker

   After a burst of failures, stop calling for a cool-down window so queues do not fill with doomed work.

2. 2

   Validate the upstream payload before trusting it

   try {
       $data = $response->toArray();
   } catch (DecodingExceptionInterface|ServerExceptionInterface $e) {
       throw new UpstreamUnavailableException('billing', $e);
   }

3. 3

   Degrade gracefully when the data is not critical

   Serve the last known good value from cache and flag the response as stale instead of failing the whole page.

Related exceptions

• Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface
• Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface
• App\Integration\Exception\UpstreamUnavailableException

Related services & controllers

Why it happens

A decline is a valid upstream answer, not a failure of the integration. It is mapped to 402 with the provider decline code preserved so the client can explain what to do next.

Common causes

• Insufficient funds, or the card is expired or blocked.
• Issuer fraud rules rejected the transaction.
• Strong customer authentication was required and not completed.
• The billing address or CVC did not match.

How to fix it

1. 1

   Pass through the decline reason, never the raw provider payload

   { "meta": { "declineCode": "insufficient_funds", "provider": "stripe", "canRetry": false } }

2. 2

   Handle the authentication-required branch

   When the provider asks for 3-D Secure, return the client secret and let the client complete the challenge.

3. 3

   Do not auto-retry a decline

   Repeated attempts increase issuer risk scores. Ask for a different payment method instead.

Related exceptions

• App\Integration\Payment\Exception\PaymentDeclinedException
• Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface

Related services & controllers

Notes for developers

Why it happens

Webhook endpoints are public, so the signature is the only proof of origin. Verification runs on the raw body before any parsing, and a mismatch rejects the delivery outright.

Common causes

• The wrong signing secret for the environment.
• The body was re-encoded by a proxy or read as a parsed array, so the raw bytes changed.
• The timestamp is outside the replay tolerance window.
• A genuine forgery attempt.

How to fix it

1. 1

   Verify against the raw request content

   $payload = $request->getContent(); // raw bytes, never the parsed array
   
   if (!hash_equals($this->sign($payload, $timestamp), $signature)) {
       throw new WebhookSignatureException();
   }

2. 2

   Compare in constant time and enforce a tolerance

   Use hash_equals and reject timestamps older than five minutes to block replays.

3. 3

   Confirm the secret bound to this environment

   php bin/console secrets:list --reveal | grep WEBHOOK

Related exceptions

• App\Integration\Exception\WebhookSignatureException
• Symfony\Component\Webhook\Exception\RejectWebhookException

Related services & controllers

Notes for developers

Why it happens

The RateLimiter component consumes a token per request. When the bucket is empty it returns the wait time, which is sent as Retry-After so callers can back off precisely.

Common causes

• A client loop without throttling, or a retry storm after a failure.
• Many users sharing one NAT address on an IP-keyed limiter.
• An import job running at full speed against a per-minute limit.
• An upstream 429 that this service surfaces to its own caller.

How to fix it

1. 1

   Honour Retry-After instead of guessing

   if (res.status === 429) {
     const wait = Number(res.headers.get("Retry-After") ?? 1) * 1000
     await sleep(wait)
     return retryOnce(request)
   }

2. 2

   Configure a limiter per audience

   framework:
     rate_limiter:
       api_authenticated:
         policy: 'token_bucket'
         limit: 120
         rate: { interval: '1 minute', amount: 120 }
       api_anonymous:
         policy: 'sliding_window'
         limit: 20
         interval: '1 minute'

3. 3

   Key on the identity, not only the IP

   Use the user or API key as the limiter key so shared addresses do not punish unrelated callers.

Related exceptions

• Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException
• Symfony\Component\RateLimiter\Exception\RateLimitExceededException

Related services & controllers

Notes for developers

Why it happens

The router throws before any controller is resolved, so this error never reaches application code.

Common causes

• A typo, or a call to a route that only exists in another version prefix.
• A missing trailing segment, or a stale client built against an older API version.
• The route is defined but its controller is excluded from the current environment.
• The reverse proxy rewrote the path before forwarding.

How to fix it

1. 1

   List what the router actually knows

   php bin/console debug:router | grep orders

2. 2

   Match on the exact path and method

   php bin/console router:match /api/v1/orders --method=POST

3. 3

   Version the API in the path

   A /api/v1 prefix makes breaking changes additive and keeps old clients working.

Related exceptions

• Symfony\Component\HttpKernel\Exception\NotFoundHttpException
• Symfony\Component\Routing\Exception\ResourceNotFoundException

Related services & controllers

Why it happens

The router matched the path and rejected the verb. The response includes an Allow header listing the supported methods.

Common causes

• POST sent where PUT or PATCH is expected.
• A browser form issuing GET to a mutation endpoint.
• A preflight OPTIONS request reaching a route that does not allow it because CORS is misconfigured.
• Partial update implemented as PATCH while the client sends PUT.

How to fix it

1. 1

   Read the Allow header from the response

   HTTP/1.1 405 Method Not Allowed
   Allow: GET, PATCH, DELETE

2. 2

   Declare methods on the route

   #[Route('/api/v1/orders/{id}', methods: ['GET', 'PATCH', 'DELETE'])]

3. 3

   Let the CORS layer answer OPTIONS

   Preflight must be handled before routing, not by an application route.

Related exceptions

• Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException
• Symfony\Component\Routing\Exception\MethodNotAllowedException

Related services & controllers

Why it happens

Anything not mapped to a specific error becomes a 500. The subscriber logs the full stack trace with the traceId and returns a deliberately opaque body so internals are never disclosed.

Common causes

• A programming error such as a null dereference or a type error.
• Missing configuration or an unset environment variable in a new deployment.
• A Messenger handler failure surfaced through HandlerFailedException.
• Exhausted memory or execution time.

How to fix it

1. 1

   Start from the traceId

   Every 500 response and every log line share the same identifier. Search the log stream by it before anything else.

   php bin/console app:logs:trace 01JC3TA2UBKL9K3O5Q7U9W1XYZ

2. 2

   Unwrap Messenger failures

   if ($e instanceof HandlerFailedException) {
       $e = $e->getPrevious() ?? $e;
   }

3. 3

   Map the root cause to a real error entry

   A 500 that repeats is a missing catalogue entry. Add a mapping in the subscriber and document it here so it becomes actionable next time.

Related exceptions

• Throwable
• Symfony\Component\Messenger\Exception\HandlerFailedException
• Symfony\Component\ErrorHandler\Error\FatalError

Related services & controllers

Notes for developers

Why it happens

A maintenance listener short-circuits the request before routing. It is a planned state, so the response advertises when to come back rather than looking like a fault.

Common causes

• A maintenance flag is set during a schema migration.
• A deployment left the flag on after finishing.
• A readiness probe reports not-ready while caches warm up.

How to fix it

1. 1

   Check and clear the flag

   php bin/console app:maintenance:status
   php bin/console app:maintenance:disable

2. 2

   Always advertise a Retry-After

   HTTP/1.1 503 Service Unavailable
   Retry-After: 120

3. 3

   Keep health endpoints outside the gate

   Probes must bypass the listener or the orchestrator will never see the service recover.

Related exceptions

• Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException
• App\Http\Exception\MaintenanceModeException

Related services & controllers