Marketplace API Documentation

🔐 Authentication Errors

Missing Authorization Header

401

MISSING-TOKEN

No authorization token was provided in the request headers.

Solution: Include your API token in the Authorization header:
Authorization: Bearer tk_your_sandbox_token_here

Invalid or Expired Token

401

INVALID-TOKEN

The provided token is invalid, malformed, or has expired.

Solution: Verify your token is correct. Sandbox tokens start with tk_, production tokens with sk_. Contact support to generate a new token if needed.

Production Token Not Allowed

403

LIVE-TOKEN-FORBIDDEN

Production tokens (sk_*) are not allowed in Phase 0 sandbox mode.

Solution: Use sandbox tokens with tk_ prefix during Phase 0. Production tokens will be enabled in Phase 1+.

Authentication Service Error

500

AUTH-INTERNAL-500

Unexpected error during authentication process.

Solution: This is a server-side error. Note the request_id from the response and contact support if the issue persists.

✅ Validation Errors

Invalid UUID Format

422

VALIDATION-UUID-422

A UUID parameter (seller-id, listing-id, etc.) is malformed or not a valid UUID v4.

Solution: Ensure UUIDs follow the format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (36 characters with hyphens).

Missing Required Field

422

VALIDATION-REQUIRED-422

A required field is missing from the request body.

Solution: Check the OpenAPI specification for required fields. Common required fields: domain, price, currency.

Invalid Price Value

422

VALIDATION-PRICE-422

Price must be a positive integer representing cents (e.g., 100000 = €1000.00).

Solution: Provide price as integer in EUR cents. Minimum: 100 (€1.00). Example: 120000 for €1200.00.

Invalid Pagination Parameters

422

VALIDATION-PAGE-400

Page or limit parameter is invalid (must be positive integers).

Solution: Use page ≥ 1 and limit between 1-100. Example: ?page=1&limit=20

📦 Resource Errors

Listing Not Found

404

LISTING-NOT-FOUND-404

The requested listing does not exist or has been deleted.

Solution: Verify the listing ID is correct. Use GET /v1/sellers/{seller-id}/listings to retrieve available listings.

Domain Already Listed

422

DOMAIN-ALREADY-LISTED-422

This domain already has an active listing.

Solution: Close or delete the existing listing before creating a new one for the same domain.

Domain Not Available

422

DOMAIN-NOT-AVAILABLE-422

The requested domain is not available for listing in the marketplace.

Solution: Use GET /v1/domains to retrieve the list of available domains.

💰 Sales & Payment Errors

Sale Not Found

404

SALE-NOT-FOUND-404

The requested sale does not exist.

Solution: Verify the sale ID is correct. Use GET /v1/sellers/{seller-id}/sales to retrieve available sales.

Sale Not Owned By Seller

403

SALE-NOT-OWNED-403

You are attempting to access a sale that belongs to another seller.

Solution: Verify the seller-id and sale-id match your account.

Payment Already Completed

409

PAYMENT-ALREADY-COMPLETED-409

Cannot modify payment details after payment has been completed.

Solution: Payment details are locked once payment is processed. Contact support if you need to update bank details for future sales.

Invalid IBAN

422

INVALID-IBAN-422

The provided IBAN is not valid (format or checksum error).

Solution: Verify your IBAN format. It should be 15-34 characters: 2 letters (country code) + 2 digits (check digits) + alphanumeric account number. Example: ES9121000418450200051332. The API validates using MOD-97 algorithm.

⏱️ Rate Limiting

Rate Limit Exceeded

429

RATE-LIMIT-EXCEEDED-429

Too many requests in a short time period.

Solution: Wait before making additional requests. Check Retry-After header for recommended wait time. Current limits: 100 requests per minute per token.

🔥 Server Errors

Internal Server Error

500

INTERNAL-ERROR-500

An unexpected error occurred while processing your request.

Solution: Note the request_id from the error response and contact support. This is logged for investigation.