Error Codes

Complete reference of Marketplace Service error codes and resolutions

Error Envelope

All errors follow the standard EventZR envelope format:

{
  "error": {
    "code": "ERR_MARKETPLACE_NOT_FOUND",
    "message": "Listing not found",
    "http": 404
  },
  "data": null,
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Error Code Index

Client Errors (400)

ERR_MARKETPLACE_BAD_REQUEST400

Bad Request

The request body or query parameters are malformed.

Resolution: Check the request payload against the API schema.

ERR_MARKETPLACE_VALIDATION422

Validation Error

One or more fields failed DTO validation (class-validator).

Resolution: Review the error details array for specific field-level issues.

ERR_MARKETPLACE_UNAUTHORIZED401

Unauthorized

Missing, expired, or invalid JWT token.

Resolution: Obtain a fresh token from /auth/v1/auth/login/email.

ERR_MARKETPLACE_FORBIDDEN403

Forbidden

Authenticated but insufficient role or wrong tenant context.

Resolution: Verify your JWT roles include the required role for this endpoint.

ERR_MARKETPLACE_NOT_FOUND404

Not Found

The requested resource does not exist or belongs to a different tenant.

Resolution: Verify the resource ID and that it belongs to your tenant.

ERR_MARKETPLACE_CONFLICT409

Conflict

Resource state conflict (e.g., publishing an already published listing, accepting an already accepted quote).

Resolution: Check the current resource state before this operation.

ERR_MARKETPLACE_RATE_LIMITED429

Rate Limited

Too many requests in the current time window.

Resolution: Implement exponential backoff and retry after the specified delay.

Server Errors (500)

ERR_MARKETPLACE_INTERNAL500

Internal Server Error

An unexpected error occurred on the server.

Resolution: Retry the request. If persistent, check CloudWatch logs for the Lambda function.

ERR_MARKETPLACE_DOWNSTREAM_UNAVAILABLE502

Bad Gateway

A downstream service (wallet-svc, integration-hub-svc, etc.) is temporarily unavailable.

Resolution: Retry after a brief delay. Check the dependent service health.

ERR_MARKETPLACE_SERVICE_UNAVAILABLE503

Service Unavailable

The marketplace service is temporarily unavailable (e.g., database connection timeout during Aurora cold start).

Resolution: Retry after 5-10 seconds. Aurora Serverless v2 may need to scale up.

ERR_MARKETPLACE_BOOTSTRAP_FAILED503

Bootstrap Failed

Lambda cold start failed (NestJS bootstrap timed out, usually due to Aurora Serverless v2 scaling).

Resolution: Retry the request. The next invocation will attempt a fresh cold start.

Business Logic Errors (Business)

ERR_MARKETPLACE_LISTING_NOT_PUBLISHED400

Listing Not Published

Cannot submit a quote on a listing that is not in "published" state.

Resolution: Ensure the listing is published before submitting quotes.