UNS API Errors

Introduction

UNS uses conventional HTTP response codes to indicate the success or failure of an API request.

UNS API HTTP Response status codes:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted).
Codes in the 5xx range indicate an error with UNS's servers.

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported. Developers could handle these types of errors programmatically.

HTTP Status Code Summary

The UNS API has a defined set of possible Status codes to return depending on the Request execution. Here's a detailed list of all possible responses a developer can expect from the UNS API

Response Status Code	Description
200 - OK	The request has been acknowledged and fully processed correctly.
201 - CREATED	The request has been acknowledged and fully processed correctly, creating a new resource.
204 - NO CONTENT	The request has been acknowledged and fully processed correctly, currently used only in the `/health` endpoint.
400 - BAD REQUEST	The request has been acknowledged and partially processed, often due a missing or bad parameter in the request.
401 - UNAUTHORIZED	The request has been acknowledged and partially processed due an invalid API Key has been provided.
402 - REQUEST FAILED	The request has been acknowledged and partially processed, due to the request was valid, but the connection was dropped.
403 - FORBIDDEN	The request has been acknowledged and partially processed, due to the developer does not have permission to perform the specific request.
404 - NOT FOUND	The request has been acknowledged and partially processed, due to the requested resource does not exist.
405 - METHOD NOT ALLOWED	The request has been acknowledged and partially processed, due to the verb provided in the API request is not valid.
409 - CONFLICT	The request has been acknowledged and partially processed, due to colliding resources with the same identifier.
429 - TOO MANY REQUESTS	The request has been acknowledged and partially processed, due to the rate limit having exceeded the defined threshold.
500 - INTERNAL SERVER ERROR	The request has not been acknowledged and partially processed due to an internal UNS error.
502, 503, 504 - SERVER ERRORS	The request has not been acknowledged nor processed.

Error Types

The UNS API will provide a flag message in the body of the API response, its purpose is to provide a brief message of the error that happened inside the API, as some errors can happen in the process of sending the request to the API.

Error Types	Description
INVALID_REQUEST_ERROR	Invalid request errors arise when your request has invalid parameters.
AUTHENTICATION_ERROR	Failure to properly authenticate to complete the request. This could be due to a bad API key, invalid Organization code, or a lack of the proper roles needed to interact with the endpoint.
FORBIDDEN	Forbidden method type when accessing resources
NOT_FOUND	Not Found errors arise when your resource does not exist.
METHOD_NOT_ALLOWED	Method not available for the caller, usually indicates that the service is not ready for that resource
CONFLICT	Conflict errors arise when a request conflicts with the current state of the target resource.
API_ERROR	API errors cover any other type of problem (e.g., a temporary problem with UNS's servers).

Error Codes

The UNS API provides a descriptive error message for each error, detailing in most cases what was the cause of the issue and a numerical error code that is different from the http status and different for each error. (e.g missing a parameter in the request, X resource not found, etc...)

# URL not found in the server
URL_NOT_FOUND = {"code": "THE_REQUESTED_URL_WAS_NOT_FOUND_ON_THE_SERVER", "num_code": 60000}

# Accessing an endpoint with a wrong Method verb.
METHOD_NOT_ALLOWED = {"code": "METHOD_NOT_ALLOWED", "num_code": 60001}

# When accessing a protected endpoint, missing credentials
MISSING_AUTHORIZATION = {"code": "MISSING_AUTHORIZATION", "num_code": 60002}

# Forbidden error code
FORBIDDEN = {"code": "FORBIDDEN", "num_code": 60003}

# Bad Request Code Error raise
BAD_REQUEST = {"code": "BAD_REQUEST", "num_code": 60004}

# Generic Validation Error
REQUEST_VALIDATION_ERROR = {"code": "REQUEST_VALIDATION_ERROR", "num_code": 60005}

# Not Found errors arise when your resource does not exist.
NOT_FOUND = {"code": "RESOURCE_NOT_FOUND", "num_code": 60006}

# Conflict errors indicates a request conflict with current state of the target resource.
CONFLICT = {"code": "CONFLICT_WITH_TARGET_RESOURCE", "num_code": 60007}

# Content length too big for http request
EXCEEDED_CONTENT_LENGTH_OF_REQUEST = {"code": "EXCEEDED_CONTENT_LENGTH_OF_REQUEST", "num_code": 60008}


# Names

# Name already taken
NAME_ALREADY_TAKEN = {"code": "NAME_ALREADY_TAKEN", "num_code": 60100}

# Name too short
NAME_TOO_SHORT = {"code": "NAME_TOO_SHORT", "num_code": 60101}

# Name too long
NAME_TOO_LONG = {"code": "NAME_TOO_LONG", "num_code": 60102}

# Name bad format
NAME_BAD_FORMAT = {"code": "NAME_BAD_FORMAT", "num_code": 60103}

# Persona_id bad format
UUID_BAD_FORMAT = {"code": "UUID_BAD_FORMAT", "num_code": 60104}

# Trademarked name
TRADEMARKED = {"code": "TRADEMARKED", "num_code": 60105}

# Name does not belong to persona
NAME_DOES_NOT_BELONG_TO_PERSONA = {"code": "NAME_DOES_NOT_BELONG_TO_PERSONA", "num_code": 60106}

# Name not found
NAME_NOT_FOUND = {"code": "NAME_NOT_FOUND", "num_code": 60107}

# Blockchain currently not supported by Olyn API
CHAIN_NOT_SUPPORTED = {"code": "BLOCKCHAIN_NOT_SUPPORTED", "num_code": 60108}

# General code for reserved names. Can be a city name, country name, merchant name, etc.
NAME_RESERVED = {"code": "NAME_RESERVED", "num_code": 60109}

# Not allowed names, i.e. bad words
NAME_NOT_ALLOWED = {"code": "NAME_NOT_ALLOWED", "num_code": 60110}

# Stripe

# Payment attempted for an unlocked name
PAYMENT_ATTEMPTED_FOR_UNLOCKED_NAME = {"code": "PAYMENT ATTEMPTED FOR UNLOCKED NAME", "num_code": 60200}

# Stripe unexpected response
STRIPE_UNEXPECTED_RESPONSE = {"code": "STRIPE_UNEXPECTED_RESPONSE", "num_code": 60201}

# Stripe invalid signature
STRIPE_INVALID_SIGNATURE = {"code": "STRIPE_INVALID_SIGNATURE", "num_code": 60202}

# Stripe webhook invalid payload
STRIPE_INVALID_PAYLOAD = {"code": "STRIPE_INVALID_PAYLOAD", "num_code": 60203}

# Stripe unable to create product
STRIPE_UNABLE_TO_CREATE_PRODUCT = {"code": "STRIPE_UNABLE_TO_CREATE_PRODUCT", "num_code": 60204}

# Bad url format
URL_BAD_FORMAT = {"code": "BAD_URL_FORMAT", "num_code": 60205}

# Bad url format
NAME_ALREADY_PAID = {"code": "NAME_ALREADY_PAID", "num_code": 60206}

# Organizations
# The organization code provided already exists
ORGANIZATION_CODE_ALREADY_EXISTS = {"code": "ORGANIZATION_CODE_ALREADY_EXISTS", "num_code": 60300}

# Invalid PublicKey
PUBLIC_KEY_INVALID = {"code": "PUBLIC_KEY_INVALID", "num_code": 60301}


# Personas

# Persona request without email and phone number
PERSONA_MISSING_REQUIRED_FIELDS = {"code": "PERSONA_MISSING_REQUIRED_FIELDS", "num_code": 60400}

# Phone number bad format
PHONE_BAD_FORMAT = {"code": "PHONE_BAD_FORMAT", "num_code": 60401}

# Email bad format
EMAIL_BAD_FORMAT = {"code": "EMAIL_BAD_FORMAT", "num_code": 60402}

# Email and phone number belong to different personas
PHONE_EMAIL_NOT_MATCH = {"code": "PHONE_EMAIL_NOT_MATCH", "num_code": 60403}

# Persona has exceeded the maximum amount of free names allowed
PERSONA_NOT_FREE_NAMES_REMAINING = {"code": "PERSONA_NOT_FREE_NAMES_REMAINING", "num_code": 60404}

# Persona not found
PERSONA_NOT_FOUND = {"code": "PERSONA_NOT_FOUND", "num_code": 60405}


# Resolver Fields

# Resolver field not allowed
RESOLVER_FIELD_NOT_ALLOWED = {"code": "RESOLVER_FIELD_NOT_ALLOWED", "num_code": 60501}

# Resolver edit not available
EDIT_RESOLVER_NOT_ALLOWED = {"code": "RESOLVER_FIELD_NOT_ALLOWED", "num_code": 60502}

# Resolver token data not mutable
TOKEN_RESOLVER_FIELD_NOT_MUTABLE = {"code": "TOKEN_RESOLVER_FIELD_NOT_MUTABLE", "num_code": 60503}

# Resolver scope not allowed
RESOLVER_SCOPE_NOT_ALLOWED = {"code": "RESOLVER_SCOPE_NOT_ALLOWED", "num_code": 60504}

# Resolver scope not found
RESOLVER_FIELD_NOT_FOUND = {"code": "RESOLVER_SCOPE_NOT_FOUND", "num_code": 60505}

# Resolver key address - Validation Failed
ADDRESS_VALIDATION_FAILED = {"code": "ADDRESS_VALIDATION_FAILED", "num_code": 60506}


# Social Connections

# Verification ID not valid
VERIFICATION_ID_NOT_VALID = {"code": "VERIFICATION_ID_NOT_VALID", "num_code": 60601}

# Social connection type not supported
SOCIAL_CONNECTION_NOT_SUPPORTED = {"code": "SOCIAL_CONNECTION_NOT_SUPPORTED", "num_code": 60602}

# Verification field not valid
VERIFICATION_FIELD_NOT_VALID = {"code": "VERIFICATION_FIELD_NOT_VALID", "num_code": 60603}

# Invalid auth code for email otp
INVALID_VERIFICATION = {"code": "INVALID_VERIFICATION", "num_code": 60604}

# Social connection not found
SOCIAL_CONNECTION_NOT_FOUND = {"code": "SOCIAL_CONNECTION_NOT_FOUND", "num_code": 60605}


# Tokens

# Social connection not found
NAME_ALREADY_TOKENIZED = {"code": "NAME_ALREADY_TOKENIZED", "num_code": 60701}


# Admin errors

# Verification ID not valid
NAME_LOCKED_BY_DIFFERENT_PERSONA = {"code": "NAME_LOCKED_BY_DIFFERENT_PERSONA", "num_code": 70101}

# Price different from model
PRICE_DIFFERENT_FROM_NAME_MODEL = {"code": "PRICE_DIFFERENT_FROM_NAME_MODEL", "num_code": 70102}

# Name not available to assign
NAME_NOT_AVAILABLE_TO_ASSIGN = {"code": "NAME_NOT_AVAILABLE_TO_ASSIGN", "num_code": 70103}

Sample Error Responses

Authentication Error:

{"error": {"type": "AUTHENTICATION_ERROR", "code":{"code":"MISSING_AUTHIRIZATION", "num_code":60002}}

Key Not Found Error:

{"error": {"type": "NOT_FOUND","code": { "code": "THE_REQUESTED_URL_WAS_NOT_FOUND_ON_THE_SERVER", "num_code": 60000 }}