If a screenshot API returns HTTP 200 for both successful captures and failures, status alone cannot tell your test whether it produced an image. Check the response status alongside its content type, body, and the endpoint’s documented success or error fields. For the specific API you are testing, use its contract—not another provider’s status codes—to define what each outcome should look like.
Why HTTP 200 is not enough
HTTP status codes describe the result and semantics of a request. RFC 9110 says that “The 200 (OK) status code indicates that the request has succeeded,” but response content still needs to be interpreted in the context of the method and API contract. For a POST request, for example, the response content can describe the processing result. If an API reports an application-level failure in a 200 response, a status-only assertion will miss it. Test transport metadata and the application-level outcome together. RFC 9110, §15.3.1.
As an Amazon Associate I earn from qualifying purchases.
Define the expected response for each scenario
Start with the endpoint’s current documentation or OpenAPI definition. For every test case, write down the expected status, media type, required body shape, stable success or error marker, and relevant headers. OpenAPI associates response definitions with HTTP status codes, making it a useful basis for comparing documented and observed behavior. OpenAPI 3.0.2.
Do not assume a particular status, error code, or schema without checking the service’s own contract. Screenshot APIs differ, and a provider’s examples are not a universal mapping.
#1 Best Overall
Validate the response representation, not just its status
For a successful capture
- Assert the status the contract specifies.
- Check that the media type matches the promised image format.
- Verify the response body is non-empty and decodes as that image format; if the contract specifies dimensions or metadata, check those too.
For a failure
- Assert the documented failure status, if the contract specifies one.
- Check the documented error media type and required fields or stable error code.
- Make sure an error response is not accepted or saved as a usable image.
For example, ScreenshotEngine documents image bytes for a successful capture and JSON for errors, and advises checking the status before treating a response as an image. That behavior is specific to its API; verify the equivalent rules in the service you use. ScreenshotEngine screenshot API quickstart.
Build a failure matrix
Choose distinct failure cases that apply to the endpoint, then record each case’s expected response from the contract. A useful starting matrix is:
| Scenario | What to assert |
|---|---|
| Valid capture | Contract-defined status; expected image media type; non-empty bytes that decode as the promised format; documented dimensions or metadata, if applicable. |
| Malformed or missing URL or options | Documented validation outcome, stable code or field errors, and no success-shaped image response. |
| Missing or invalid credentials | Documented authentication outcome and error representation. |
| Blocked or inaccessible target | Documented target or rendering failure behavior. |
| Rate limit or exhausted quota | Documented limit outcome and any retry or reset headers or fields the contract defines. |
| Renderer failure or timeout | Documented failure signal; retry only when the contract says it is appropriate. |
These are categories to consider, not guaranteed responses. The cases that apply and their status codes, fields, and headers depend on the API. For each case, check the service’s documentation rather than transplanting another provider’s mapping.
Free tools Windows power users keep installed
One-click scans. No signup required.
Assert stable signals and account for retries
Prefer machine-readable error codes, required schema fields, documented headers, and explicit success markers. Treat human-readable messages as secondary unless the API promises their exact wording. Failure shapes may vary depending on where request processing stops, so do not require every error to contain identical fields unless the contract says so.
Rank #3
If the contract covers side effects, include them in the test: for example, whether a failed request creates an artifact, consumes quota, or may be retried. A client timeout does not necessarily mean the capture failed; ScreenshotEngine notes that capture can succeed before the client times out, so a retry can create another successful request. That is a provider-specific caution, not a general guarantee. ScreenshotEngine screenshot API quickstart.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Make “200 plus error” fail the right test
For a scenario the contract says should fail, the test should reject a success-shaped image response and positively assert the documented failure signal. If the API explicitly specifies HTTP 200 for every outcome, assert the body-level success or failure discriminator instead. In that case, record the status behavior as part of the contract; do not treat 200 itself as proof that a screenshot was produced.
This is a test-design template, not a report of tests run against a particular API. The expected values must come from the service’s current contract.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
