Error Codes

    All error responses return a JSON body with a message field. Security-sensitive endpoints return generic messages to prevent information disclosure.

    Response Format

    json
    {
  "message": "Validation failed: phoneNumber must be in E.164 format"
}

    Status Codes

    CodeNameDescription
    400Bad RequestThe request body or parameters are invalid. Check the error message for specifics.
    401UnauthorizedInvalid or missing API key. Check your x-api-key header.
    402Payment RequiredYour workspace tier does not have access to this feature. Upgrade to Starter or above to use API keys.
    403ForbiddenYour workspace does not have access to this resource.
    404Not FoundThe requested resource does not exist or belongs to a different workspace.
    409ConflictThe request conflicts with the current state (e.g., job already running).
    429Too Many RequestsRate limit exceeded. Retry after the number of seconds specified in the Retry-After header.
    500Internal Server ErrorAn unexpected error occurred. Contact support if the issue persists.

    SDK error types

    The SDKs raise typed exceptions, so you can either catch by status code or by class. All API error subclasses inherit from NopaqueAPIError and carry status, code, details, and request_id / requestId.

    HTTPException class
    400ValidationError
    401AuthenticationError
    403PermissionError
    404NotFoundError
    409ConflictError
    429RateLimitError (carries retry_after / retryAfter)
    5xxServerError
    –APIConnectionError (network failure, including S3 PUT/GET)
    –APITimeoutError (request exceeded timeout)
    python
    from nopaque import Nopaque, NotFoundError, RateLimitError

client = Nopaque()

try:
    job = client.mapping.get("map_does_not_exist")
except NotFoundError as e:
    print(f"Not found: {e.message}, request_id={e.request_id}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")