Errors

Error HandlingCopy Anchor Link

The Aftermarket Portfolio API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include detailed information to help you identify and resolve issues.

Error Response FormatCopy Anchor Link

All error responses follow a consistent JSON structure:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error description",
  "details": "More details about the error",
  "fields": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Human-readable error description",
      "path": "Query parameter or request body field which failed validation"
    }
  ]
}

HTTP Status CodesCopy Anchor Link

2xx SuccessCopy Anchor Link

• 200 OK: Request succeeded
• 201 Created: Resource created successfully
• 204 No Content: Request succeeded with no response body

4xx Client ErrorsCopy Anchor Link

• 400 Bad Request: Invalid request syntax or parameters
• 401 Unauthorized: Missing or invalid authentication credentials
• 403 Forbidden: Valid credentials but insufficient permissions
• 404 Not Found: Requested resource doesn't exist
• 409 Conflict: Resource already exists
• 422 Unprocessable Entity: A business-rule conflict, or a downstream service rejected the request for a reason that doesn't fit a per-item result (see below)
• 429 Too Many Requests: Rate limit exceeded

5xx Server ErrorsCopy Anchor Link

• 500 Internal Server Error: Unexpected server error, including a downstream dependency returning an error
• 503 Service Unavailable: The authentication service is temporarily unreachable
• 504 Gateway Timeout: A downstream dependency didn't respond in time. Only Get job results and Upload data to job can return this; every other endpoint surfaces a downstream timeout as 500 instead

Common Error CodesCopy Anchor Link

400 Bad RequestCopy Anchor Link

BAD_REQUEST

{
  "code": "BAD_REQUEST",
  "message": "Invalid request body"
}

400 is also used for validation errors

{
  "code": "BAD_REQUEST",
  "message": "Invalid request body",
  "fields": [
  {
    "code": "VALIDATION_ERROR",
    "path": "name",
    "message": "'invalid_domain.invalid_tld' is not a valid value for name (see documentation for valid values)"
  },
  {
    "code": "VALIDATION_ERROR",
    "path": "displayName",
    "message": "'Invalid_domain.Invalid_tld' is not a valid value for displayName (see documentation for valid values)"
  }
]
}

And finally its also used for bulk operation jobs in case the limit has been reached. TOO_MANY_JOBS

{
  "code": "TOO_MANY_JOBS",
  "message": "Unable to create new bulk operation job",
  "detail": "Unable to create new bulk operation job with 3 or more in created state. Please use one of the previous jobs in the created state instead"
}

401 UnauthorizedCopy Anchor Link

Besides the account-linkage errors below, a malformed or invalid Authorization header returns one of several AUTH_CODE_* codes (for example AUTH_CODE_API_KEY_MISSING, AUTH_CODE_API_KEY_SECRET_INVALID, AUTH_CODE_API_KEY_SECRET_AUTHORIZATION_HEADER_MALFORMED) — see the Authentication guide for the expected header format.

CUSTOMER_NOT_FOUND

{
  "code": "CUSTOMER_NOT_FOUND",
  "message": "Could not find Afternic user for your account. Please contact support."
}

CUSTOMER_LINK_NOT_FOUND

{
  "code": "CUSTOMER_LINK_NOT_FOUND",
  "message": "Could not find a linked Afternic user for your GoDaddy account. Please contact support"
}

CUSTOMER_ID_MISMATCH This usually happens in case the Customer ID does not match with what is parsed in the Authentication Token.

{
  "code": "CUSTOMER_ID_MISMATCH",
  "message": "Customer ID does not match the authenticated token"
}

403 ForbiddenCopy Anchor Link

CUSTOMER_ACCESS_DENIED

{
  "code": "CUSTOMER_ACCESS_DENIED",
  "message": "Customer is not allowed to access this resource"
}

404 Not FoundCopy Anchor Link

RESOURCE_NOT_FOUND

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "The requested domain was not found in your portfolio"
}

409 ConflictCopy Anchor Link

CONFLICT

{
  "code": "CONFLICT",
  "message": "Domain 'example.com' already exists"
}

Only Create domain returns this, for a domain you already own. A conflict on an existing domain (e.g. it's on hold) is reported as 422 instead — see below.

422 Unprocessable EntityCopy Anchor Link

Returned for two different reasons, depending on the operation:

On Delete domain, a business-rule conflict (e.g. the domain is on hold) is reported with this API's own VALIDATION_ERROR code rather than a new top-level status:

VALIDATION_ERROR

{
  "code": "VALIDATION_ERROR",
  "message": "Domain 'example.com' is on hold and cannot be deleted"
}

On Upsert multiple domains, Relist multiple domains (when the request as a whole is invalid, rather than one item in it), and several other single-item write operations (Create domain, Replace domain, Update domain, Update job, Upload data to job, Update sale, Send sale message), this is returned when a downstream service's own validation rejects the request. The top-level code there is relayed verbatim from that service, not one of this API's own codes, and varies by the kind of failure — including at least the two below.

MALFORMED_INPUT — a request-shape validation failure

{
  "code": "MALFORMED_INPUT",
  "message": "Validation errors parsing request",
  "fields": [
    {
      "code": "VALIDATION_ERROR",
      "path": "domain",
      "message": "must use only lowercase characters"
    }
  ]
}

DEPENDENCY_ISSUE — a business-rule/state-conflict validation failure

{
  "code": "DEPENDENCY_ISSUE",
  "message": "Status has to be either CLOSED or CANCELED"
}

429 Too Many RequestsCopy Anchor Link

RATE_LIMIT_EXCEEDED

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests"
}

500 Internal Server ErrorCopy Anchor Link

INTERNAL_SERVER_ERROR

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}

DEPENDENCY_ISSUE

{
  "code": "DEPENDENCY_ISSUE",
  "message": "Unable to communicate with downstream service"
}

Account resolution (which runs on every authenticated request) can also surface its own downstream failures at 500, with the underlying error's own code rather than one of the two above:

HTTP_CLIENT_ERROR — the account-linkage service couldn't be reached

{
  "code": "HTTP_CLIENT_ERROR",
  "message": "Internal Error occurred while fetching Afternic User. Please contact support."
}

UNMARSHAL_ERROR — the account-linkage service returned a response that couldn't be parsed

{
  "code": "UNMARSHAL_ERROR",
  "message": "Internal Error occurred while fetching Afternic User. Please contact support."
}

503 Service UnavailableCopy Anchor Link

AUTH_CODE_AUTH_SERVICE

{
  "code": "AUTH_CODE_AUTH_SERVICE",
  "message": "Auth service is unavailable"
}

This means the authentication service itself is down, not your credentials — retry with backoff.

504 Gateway TimeoutCopy Anchor Link

REQUEST_TIMEOUT

{
  "code": "REQUEST_TIMEOUT",
  "message": "Downstream request timeout"
}

Error Handling Best PracticesCopy Anchor Link

1. Always Check Status Codes: Don't assume success, check the HTTP status
2. Parse Error Details: Use the error code and details for specific handling
3. Implement Retry Logic:
   • Retry 5xx errors with exponential backoff
   • Respect Retry-After header for 429 errors
   • Don't retry 4xx errors (except 429)
4. Log Request IDs: Include X-Request-Id when contacting support
5. Handle Network Errors: Implement timeouts and connection error handling

Need Help?Copy Anchor Link

If you encounter persistent errors:

1. Check the error code and message
2. Verify your request format and parameters
3. Ensure your API credentials are valid
4. Contact Afternic Support with the X-Request-Id