Error Codes

📋

Use appropriate HTTP status codes to communicate the outcome of requests from YGG Redeem.

💡

errorCode are optional, but recommended to use for error handling. It's very useful for debugging and error tracking.

HTTP Status Codes

Your API should return these standard HTTP status codes:

Status Code	Meaning	When to Use	Response Signature Required
`200 OK`	Success	✅ Always use this for successful responses	✅ YES - Must include `X-API-SIGNATURE`
`400 Bad Request`	Invalid request	Invalid request body or query parameters	❌ No signature needed
`401 Unauthorized`	Authentication failed	Missing or invalid `X-API-KEY` or `X-API-SIGNATURE`	❌ No signature needed
`404 Not Found`	Resource not found	User address doesn't exist in your system	❌ No signature needed
`409 Conflict`	Conflict	Request already processed	❌ No signature needed
`422 Unprocessable Entity`	Unprocessable Entity	Business logic failure	❌ No signature needed
`429 Too Many Requests`	Rate limited	Too many requests in a given time period	❌ No signature needed
`500 Internal Server Error`	Server error	Unexpected server error on your side	❌ No signature needed

⚠️

Important: Use success: true | false for all JSON responses (including 200 OK, 4XX and 5XX) to indicate the actual result.

🔑

Critical: For 200 OK responses, you MUST generate X-API-SIGNATURE and include it in response headers. For all other HTTP status codes, no signature is required.

Response Format

Success Response Structure

{
  "success": true,
  // ... additional required fields per endpoint
}

Error Response Structure

{
  "success": false,
  "errorCode": "ERR-INSUFFICIENT-POINTS",
  "errorMessage": "User does not have enough points for this redemption"
}

Common Error Codes

Authentication Errors

Error Code	HTTP Status	Description	Solution
`ERR-AUTH-FAILED`	`401`	Invalid or missing API key	Check `X-API-KEY` header
`ERR-INVALID-SIGNATURE`	`401`	HMAC signature mismatch	Verify signature generation
`ERR-MISSING-HEADERS`	`401`	Required headers missing	Include all auth headers
`ERR-EXPIRED-REQUEST`	`401`	Request timestamp too old	Check UUIDv7 timestamp

User & Address Errors

Error Code	HTTP Status	Description	Solution
`ERR-USER-NOT-FOUND`	`404`	Wallet address not found	User needs to register first
`ERR-INVALID-ADDRESS`	`400`	Malformed wallet address	Validate address format
`ERR-ADDRESS-MISMATCH`	`400`	Address doesn't match records	Verify user identity

Points & Balance Errors

Error Code	HTTP Status	Description	Solution
`ERR-INSUFFICIENT-POINTS`	`422`	Not enough points to deduct	User needs more points
`ERR-INVALID-AMOUNT`	`422`	Invalid point amount	Check for negative or zero values
`ERR-AMOUNT-MISMATCH`	`422`	Deduct amount doesn't match original	Verify transaction amounts
`ERR-ZERO-BALANCE`	`422`	User has no points	User needs to earn points

Transaction Errors

Error Code	HTTP Status	Description	Solution
`ERR-DUPLICATE-REQUEST`	`409`	Request already processed	Check `yggRedemptionId` uniqueness
`ERR-TRANSACTION-NOT-FOUND`	`404`	Original transaction not found	Verify `partnerTransactionId`
`ERR-ALREADY-REVERTED`	`409`	Transaction already reversed	Check transaction status
`ERR-TRANSACTION-FAILED`	`500`	Database transaction failed	Retry or check system health

System Errors

Error Code	HTTP Status	Description	Solution
`ERR-INTERNAL`	`500`	Unexpected server error	Check server logs
`ERR-DATABASE-ERROR`	`500`	Database connection failed	Check database connectivity
`ERR-TIMEOUT`	`504`	Request processing timeout	Retry or check system load
`ERR-MAINTENANCE`	`503`	System under maintenance	Wait and retry later

Error Handling Best Practices

1. Consistent Error Format

Always use the same error response structure:

{
  "success": false,
  "errorCode": "ERR-CODE-HERE",
  "errorMessage": "Human-readable description",
  "timestamp": "2025-08-06T06:50:32.426Z", // Optional
  "requestId": "uuid-from-x-api-request"    // Optional for debugging
}

2. Meaningful Error Messages

💡

Good: "User does not have enough points. Available: 500, Required: 1000"

Bad: "Error occurred"

3. Error Logging

Log all errors with sufficient context:

console.error({
  errorCode: 'ERR-INSUFFICIENT-POINTS',
  userId: user.id,
  address: request.address,
  availablePoints: user.points,
  requestedPoints: request.deductPoints,
  yggRedemptionId: request.yggRedemptionId,
  timestamp: new Date().toISOString()
});

4. Rate Limiting

When implementing rate limiting, provide helpful information:

{
  "success": false,
  "errorCode": "ERR-RATE-LIMITED",
  "errorMessage": "Too many requests. Try again in 60 seconds",
  "retryAfter": 60,
  "maxRequests": 100,
  "windowSeconds": 3600
}

HTTP Status Code Examples

Authentication Failure

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{
  "success": false,
  "errorCode": "ERR-INVALID-SIGNATURE",
  "errorMessage": "HMAC signature validation failed"
}

Invalid Request

HTTP/1.1 400 Bad Request
Content-Type: application/json
 
 
{
  "success": false,
  "errorCode": "ERR-INVALID-REQUEST",
  "errorMessage": "Invalid request body"
}

Request Already Processed

HTTP/1.1 409 Conflict
Content-Type: application/json
 
 
{
  "success": false,
  "errorCode": "ERR-DUPLICATE-REQUEST",
  "errorMessage": "Request already processed"
}

Business Logic Failure

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
 
{
  "success": false,
  "errorCode": "ERR-INSUFFICIENT-POINTS",
  "errorMessage": "User has 500 points but requested 1000"
}

Server Error

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
 
{
  "success": false,
  "errorCode": "ERR-DATABASE-ERROR",
  "errorMessage": "Unable to connect to database"
}

🚨

Emergency Contact: If you encounter persistent errors, contact the YGG integration team immediately through our Slack channel #ext-redeem-partnerships.

Confirm Redemption Glossary