Errors

Waysdrop returns a consistent error envelope for HTTP exceptions (via the global exception filter).

Error envelope

All errors use this structure:

{
    "statusCode": 500,
    "method": "POST",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/request",
    "url": "https://api.waysdrop.com/api/request",
    "message": "Internal server error",
    "environment": "staging"
}

Field meanings

statusCode: HTTP status code
method: HTTP method
timestamp: ISO timestamp when the error was generated
path: request path without query string
url: full request URL (includes query string)
message: human-readable error message
environment: server environment label

API key auth errors

Missing API key

Status: 401 Unauthorized
Message: API key is required

{
    "statusCode": 401,
    "method": "GET",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/countries",
    "url": "https://api.waysdrop.com/api/countries",
    "message": "API key is required",
    "environment": "live"
}

Invalid API key format

API keys must match: wsp_(live|staging)_[a-f0-9]{64} Status: 401 Unauthorized
Message: Invalid API key format

{
    "statusCode": 401,
    "method": "GET",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/countries",
    "url": "https://api.waysdrop.com/api/countries",
    "message": "Invalid API key format",
    "environment": "live"
}

Invalid or inactive API key

Status: 401 Unauthorized
Message: Invalid API key

{
    "statusCode": 401,
    "method": "GET",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/countries",
    "url": "https://api.waysdrop.com/api/countries",
    "message": "Invalid API key",
    "environment": "live"
}

Rate limits / quota

API quota exceeded

Status: 429 Too Many Requests
Message: API quota exceeded

{
    "statusCode": 429,
    "method": "GET",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/some/path",
    "url": "https://api.example.com/some/path?x=1",
    "message": "API quota exceeded",
    "details": {
        "message": "API quota exceeded",
        "error": "Too Many Requests",
        "quota": {
            "limit": 123,
            "remaining": 0,
            "resetAt": "2026-01-24T12:34:56.789Z",
            "resetIn": 42
        }
    },
    "environment": "staging"
}

Business errors

Insufficient balance

Returned when wallet debit fails (e.g., creating a delivery request). Status: 422 Unprocessable Entity
Message: Insufficient balance

{
    "statusCode": 422,
    "method": "POST",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/request",
    "url": "https://api.waysdrop.com/api/request",
    "message": "Insufficient balance",
    "environment": "live"
}

Payment required

Returned when wallet debit fails for api usage Status: 402 Payment Required
Message: Insufficient wallet balance for API usage

{
    "statusCode": 402,
    "method": "POST",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/request",
    "url": "https://api.waysdrop.com/api/request",
    "message": "Insufficient wallet balance for API usage",
    "environment": "live"
}

Validation errors

Request validation errors are returned as 400 Bad Request and the message contains a semi-colon separated list.

{
    "statusCode": 400,
    "method": "POST",
    "timestamp": "2026-01-24T12:34:56.789Z",
    "path": "/api/request",
    "url": "https://api.waysdrop.com/api/request",
    "message": "destinationContactEmail: must be an email; packagesId: each value in packagesId must be a UUID",
    "environment": "live"
}

Success responses

Most successful API responses use:

{
    "success": true,
    "message": "Pricing fetched successfully",
    "data": {}
}

Some endpoints respond with 204 No Content (no JSON body).

Get started

API reference

Errors

Errors

Error envelope

API key auth errors

Missing API key

Invalid API key format

Invalid or inactive API key

Rate limits / quota

API quota exceeded

Business errors

Insufficient balance

Payment required

Validation errors

Success responses

​Errors

​Error envelope

​API key auth errors

​Missing API key

​Invalid API key format

​Invalid or inactive API key

​Rate limits / quota

​API quota exceeded

​Business errors

​Insufficient balance

​Payment required

​Validation errors

​Success responses

Errors

Error envelope

API key auth errors

Missing API key

Invalid API key format

Invalid or inactive API key

Rate limits / quota

API quota exceeded

Business errors

Insufficient balance

Payment required

Validation errors

Success responses