Skip to main content

Troubleshooting

Start with the HTTP status, Problem code, and request_id. Never paste the API key or raw email into a ticket.

401 invalid_credentials​

Confirm that X-API-Key is present at runtime and has no copied quotes or whitespace. The response is deliberately generic: do not use repeated requests to infer whether a key exists, expired, or was revoked. Request replacement if exposure or revocation is possible.

403​

The credential authenticated but is not authorized for this operation in its assigned organization, customer, environment, or capability. A test credential does not become a production credential by changing the base URL. Adding customer selectors will not fix authorization.

404 or 405​

Use exactly POST https://api.phishinghermes.com/v1/email-analyses, without a trailing slash. Do not combine a base URL ending in /v1 with a path starting in /v1.

408 request_body_timeout​

Hermes did not receive the complete request body within the body-read deadline. Check upload and proxy behavior, then retry the same immutable bytes with the same idempotency key and bounded backoff.

409 idempotency_conflict​

The key was used with different bytes. Recover the original byte buffer and retry with the original key, or create a new key only for a genuinely new logical submission. A still-processing original request is reported as 503 idempotency_in_progress, not 409.

413 payload_too_large​

The body exceeded 10,485,760 bytes. Do not silently remove attachments or truncate headers because that changes security evidence.

415​

Send raw bytes with Content-Type: message/rfc822. Omit Content-Encoding or use identity. Do not send JSON, form data, gzip, or base64-wrapped input.

422​

Verify that the file is non-empty, contains no NUL bytes, and has recognizable headers plus a body. email_too_complex means a structural MIME or header limit was exceeded.

Network timeout, 429, 500, or 503​

Retry with the same key and exact bytes using a finite attempt count, finite total deadline, exponential backoff, and jitter. Honor Retry-After when present. Do not assume it will be present.

For analysis_outcome_unknown, never generate another key to force a new analysis. Stop after bounded retries and contact support.

Partial response​

A partial response is a successful public transaction containing confirmed evidence, but not a “clean” declaration. Confirmed threats are preserved. Without confirmed threat evidence, an incomplete applicable analysis returns inconclusive, unknown, and partial.

Contact support​

Email info@phishinghermes.com with:

  • the latest request_id;
  • approximate UTC time;
  • status and Problem code;
  • client library and version;
  • whether retries preserved the same key and bytes.

Do not include credentials, full headers, message bodies, or attachments unless Hermes establishes a separately approved secure exchange.