Abort Censys annotation if we run out of credits

[phillip-stephens]

Before, we only logged the error if Censys returned a non-200 status code and then continued. Especially in cases like API token exhaustion, this would lead to a case where annotations at the start would work correctly and then silently fail.

This PR changes it so any 4XX error will abort the annotation. 500 is listed as a transient server error so those are just logged and we continue.

Specific HTTP statuses I've seen are:

• 401 Unauthorized - Personal Access token is not correct
• 422 - No token budget available
  • I couldn't find this specific error precisely documented anywhere, the API docs just say you'll get an error if you run out of credits. Therefore, I thought it best to just return the exact error message Censys provides rather than hard-code error text based on un-documented behavior.

422 Example

FATA[0000] censys api returned an http status '422 Unprocessable Entity' with message: '{"title":"Unprocessable Entity","status":422,"detail":"Unprocessable Entity","errors":[{"message":"insufficient balance"}]}'. Cannot continue to annotate, please check that you have sufficient API credits and your PAT is correct 

401 Example

FATA[0000] censys api returned an http status '401 Unauthorized' with message: '{"error":{"code":401,"status":"Unauthorized","request":"bd3c3588695b3720e220dd77d8437d6f","reason":"Access token is not active","message":"Access credentials are invalid"}}'. Cannot continue to annotate, please check that you have sufficient API credits and your PAT is correct 

200 Example

⋊> ~/zannotate on phillip/abort-if-no-censys-tokens ◦ shuf -n 1 large_input.txt | ./zannotate --censys --censys-pat=XXXXXXXXXX
                    
{"ip":"167.93.60.70","censys":{"autonomous_system":{"asn":33132,"description":"CROWNCASTLE-AS33132 - Crown Castle Fiber LLC","bgp_prefix":"167.93.0.0/17","name":"CROWNCASTLE-AS33132 - Crown Castle Fiber LLC","country_code":"US"},"whois":{"network":{"cidrs":["167.93.0.0/16"],"created":"1993-05-20T00:00:00Z","updated":"2021-12-14T00:00:00Z","allocation_type":"ALLOCATION","handle":"VOLUSIA","name":"School District of Volusia County"},"organization":{"country":"US","admin_contacts":[{"handle":"HILTO51-ARIN","name":"Matt Hilton","email":"mahilton@volusia.k12.fl.us"}],"handle":"SDVC-Z","name":"School District of Volusia County","postal_code":"32720","abuse_contacts":[{"handle":"CMA364-ARIN","name":"Carlos Ayala","email":"cmayala@volusia.k12.fl.us"},{"handle":"HILTO51-ARIN","name":"Matt Hilton","email":"mahilton@volusia.k12.fl.us"},{"handle":"WBS2-ARIN","name":"William Steele","email":"wbsteele@volusia.k12.fl.us"}],"tech_contacts":[{"handle":"CMA364-ARIN","name":"Carlos Ayala","email":"cmayala@volusia.k12.fl.us"},{"handle":"HILTO51-ARIN","name":"Matt Hilton","email":"mahilton@volusia.k12.fl.us"},{"email":"wbsteele@volusia.k12.fl.us","handle":"WBS2-ARIN","name":"William Steele"}],"street":"200 No. Clara Ave","city":"Deland","state":"FL"}},"dns":{"reverse_dns":{"resolve_time":"2026-05-03T05:05:07Z"}},"ip":"167.93.60.70","location":{"timezone":"America/New_York","province":"Florida","coordinates":{"latitude":30.33218,"longitude":-81.65565},"continent":"North America","country":"United States","country_code":"US","city":"Jacksonville","postal_code":"32202"}}}
00h:00m:00s; Scan Complete; 1 ips annotated; 1.76 ips/sec