>_ API Error Handling Testing Checklist

Short answer

An API Error Handling Testing Checklist is a focused checklist that helps verify whether an API returns clear, safe, predictable, and useful errors for invalid requests, authentication failures, permission problems, missing resources, conflicts, rate limits, timeouts, external service failures, and server errors.

This article does not replace an API Testing Checklist.

An API Testing Checklist checks the API overall:

• endpoints;
• status codes;
• schema;
• validation;
• authentication;
• authorization;
• CRUD;
• pagination;
• performance;
• integration behavior.

An API Error Handling Testing Checklist focuses only on how the API behaves when something goes wrong:

• does it return the correct status code?
• is the error message understandable?
• are field-level errors available?
• does the API avoid exposing stack traces, SQL details, tokens, or secrets?
• is the error response format consistent?
• can the issue be found by request ID?
• does the API handle timeouts, rate limits, and external provider failures correctly?
• does the error avoid creating partial data or duplicate records?
• are errors visible in logs and monitoring?

The main idea is: API error handling testing checks whether an API returns clear, safe, predictable, and useful errors for invalid requests, authentication failures, permission problems, missing resources, rate limits, timeouts, external service failures, and server errors.

API Error Handling Testing vs API Testing

API Testing answers the question: does the API endpoint work correctly?

For example:

• GET /users/{id} returns the correct user;
• POST /orders creates an order;
• PATCH /profile updates a profile;
• response schema matches expectations;
• valid request returns success.

API Error Handling Testing answers the question: what happens when the request is invalid, unauthorized, forbidden, too large, duplicated, expired, rate-limited, or affected by an external dependency failure?

For example:

• POST /users without email returns 400, not 500;
• expired token returns 401;
• regular user calling an admin endpoint receives 403;
• nonexistent resource returns 404;
• duplicate create request returns 409 or a safe idempotent response;
• rate limit returns 429;
• external provider failure does not mark the operation as successful;
• server error does not expose stack trace.

In simple terms:

API Testing: does the endpoint work? API Error Handling Testing: does the endpoint fail correctly, safely, and clearly?

API Error Handling Testing vs API Test Cases Checklist

An API Test Cases Checklist is a set of specific API scenarios:

• valid GET;
• invalid POST;
• missing field;
• expired token;
• duplicate request;
• pagination;
• filtering;
• authorization;
• rate limit.

An API Error Handling Testing Checklist is narrower and focuses on error behavior:

• error response structure;
• status codes;
• field-level validation errors;
• authentication errors;
• permission errors;
• conflict errors;
• timeout errors;
• external API errors;
• safe messages;
• request IDs;
• logs;
• monitoring;
• production error smoke.

An API Test Cases Checklist may include error cases. But this article goes deeper into the quality, safety, and predictability of API errors.

API Error Handling vs REST API Security Testing

A REST API Security Testing Checklist checks whether the API can be used unsafely:

• access to another user’s objects;
• mass assignment;
• unsafe methods;
• sensitive data exposure;
• token handling;
• CORS;
• rate limits;
• security misconfiguration.

An API Error Handling Testing Checklist checks how the API reports errors:

• does the error expose sensitive information?
• does it show a stack trace?
• does it confirm the existence of a private resource when it should not?
• does it return a safe error format?
• does it include a request ID for debugging?
• does it avoid turning expected client errors into 500 responses?

These topics overlap. For example, an unsafe error message is both an error handling issue and a security issue.

API Error Handling vs API Integration Testing

An API Integration Testing Checklist checks whether a business process works between systems through APIs.

For example:

• e-commerce sends an order to ERP;
• payment provider sends a webhook;
• CRM receives a lead;
• retry does not create duplicate data.

An API Error Handling Testing Checklist checks how the API behaves when something goes wrong:

• external CRM returns a validation error;
• payment provider times out;
• ERP is unavailable;
• webhook payload is invalid;
• external API returns 429;
• downstream service returns malformed response.

An API integration may be designed correctly, but error handling can still be weak: failures may be lost, status may remain “success,” logs may be empty, or retries may create duplicates.

When to use an API Error Handling Testing Checklist

Use this checklist whenever an API needs to handle errors reliably and safely.

For example:

• a new REST API is launching;
• a new endpoint is added;
• validation changes;
• request schema changes;
• error response format changes;
• authentication is added;
• roles or permissions change;
• rate limiting is added;
• idempotency is added;
• external provider integration is added;
• webhook endpoint is added;
• file upload API changes;
• async job is added;
• a bug where invalid request returned 500 is being fixed;
• an unsafe error message bug is being fixed;
• a duplicate request bug is being fixed;
• API regression is performed before release;
• production smoke is performed after backend deployment.

For a small endpoint change, a short error smoke test may be enough. For a public API, partner API, payment API, multi-tenant SaaS API, or backend with integrations, it is better to go through the full API Error Handling Testing Checklist.

Short API Error Handling Testing Checklist

If you need a quick API error handling smoke test, check that:

• missing required field returns 400;
• invalid JSON returns 400, not 500;
• invalid path parameter returns safe client error;
• invalid query parameter returns safe client error;
• request without token returns 401;
• expired token returns 401;
• regular user on admin endpoint returns 403;
• nonexistent resource returns 404;
• duplicate resource creation returns 409 or documented error;
• unsupported method returns 405;
• unsupported content type returns 415 or documented error;
• rate-limited request returns 429;
• request timeout is handled;
• external provider failure is handled;
• duplicate request does not create duplicate data;
• idempotency conflict returns clear error;
• error response follows standard schema;
• error response includes useful error code;
• field-level validation error points to correct field;
• error includes request ID or correlation ID;
• error does not expose stack trace;
• error does not expose SQL, internal paths, tokens, secrets, or full payment data;
• errors are logged safely;
• monitoring detects error spikes;
• production-safe error smoke has passed after release.

Good API Error Response Example

A good API error response should be clear for the client, useful for debugging, and safe from a security perspective.

Example:

Response fields:

• error.code: VALIDATION_ERROR;
• error.message: Email is required.;
• error.field: email;
• error.requestId: req_123;

What is good about this response:

• code gives a stable machine-readable error code;
• message explains the problem to a human;
• field shows which field caused the error;
• requestId helps find the request in logs;
• response does not contain stack trace;
• response does not contain SQL details;
• response does not contain secrets;
• response does not expose internal implementation.

For multiple validation errors, an array can be used:

Response fields:

• error.code: VALIDATION_ERROR;
• error.message: Request validation failed.;
• error.fields[0].field: email;
• error.fields[0].message: Email is required.;
• error.fields[1].field: password;
• error.fields[1].message: Password must be at least 8 characters.;
• error.requestId: req_456;

Bad API Error Response Example

A bad API error response can be useless or unsafe.

Example:

Response fields:

• error: Internal Server Error;
• stack: Error at UserService.createUser /app/src/user.js:42;
• sql: INSERT INTO users...;
• token: eyJhbGciOi...;

Problems:

• exposes stack trace;
• shows internal file path;
• shows SQL details;
• may expose token;
• does not provide stable error code for the client;
• does not help the user fix the request;
• creates security risk.

API Error Handling Testing Checklist

1. Define API error handling scope

Before testing, define which endpoints and error scenarios are in scope.

Check that:

• endpoints to test are known;
• public endpoints are known;
• protected endpoints are known;
• admin-only endpoints are known;
• endpoints that create/update/delete data are known;
• endpoints that depend on external providers are known;
• file endpoints are known;
• async endpoints are known;
• business-critical endpoints are known;
• production errors are known;
• error formats are known;
• clients depending on error format are known;
• pass / fail decision owner is known.

The main question is: which API errors can affect users, integrations, data consistency, security, or release readiness?

2. Check standard error response schema

API errors should be consistent.

Check that:

• all errors use consistent structure;
• error object is present;
• machine-readable error code is present;
• human-readable message is present;
• request ID or correlation ID is present;
• field-level errors are present when needed;
• timestamp is present if product uses it;
• documentation link is present if product uses it;
• response format is consistent across endpoints;
• errors are not returned as random strings;
• HTML error pages are not returned for JSON API;
• frontend/mobile/integrations can parse error consistently.

Security and usability question: can the client reliably understand and handle the API error?

3. Check missing required field errors

Missing required fields are one of the most common API errors.

Test cases:

• missing email;
• missing password;
• missing name;
• missing amount;
• missing currency;
• missing resource ID;
• missing required nested object;
• missing required array;
• missing required file;
• missing required query parameter.

Expected result:

• status is 400 Bad Request;
• error identifies missing field;
• no record is created;
• no partial data is saved;
• response follows standard error schema;
• message is clear enough for API consumer.

4. Check invalid JSON body

Malformed JSON should not create 500.

Test cases:

• broken JSON syntax;
• missing closing brace;
• trailing comma;
• invalid string escaping;
• wrong top-level type;
• empty body where JSON required.

Expected result:

• status is 400 Bad Request;
• error message is safe and clear;
• no stack trace;
• no parser internals exposed;
• no data is created or changed;
• request is logged safely.

5. Check invalid data type errors

API should reject wrong data types predictably.

Test cases:

• string instead of number;
• number instead of string;
• string instead of boolean;
• object instead of array;
• array instead of object;
• null where value is required;
• decimal where integer is required.

Expected result:

• status is 400;
• field-level error identifies incorrect field;
• expected type is clear if product allows it;
• no server error;
• no unsafe type coercion.

Example:

Response fields:

• quantity: three;

Expected: validation error, not silent conversion or server crash.

6. Check invalid format errors

Invalid formats should be rejected with useful messages.

Test cases:

• invalid email;
• invalid phone;
• invalid date;
• invalid datetime;
• invalid UUID;
• invalid URL;
• invalid currency code;
• invalid country code;
• invalid postal code;
• invalid file name;
• invalid enum value.

Expected result:

• status is 400;
• error identifies field;
• expected format is clear enough;
• no internal validation details exposed;
• invalid data is not saved.

7. Check invalid path parameter errors

Path parameters often identify resources.

Test cases:

• invalid ID format;
• nonexistent ID;
• negative ID;
• very large ID;
• ID belonging to another user;
• ID belonging to another tenant;
• deleted resource ID;
• archived resource ID.

Expected result:

• invalid format returns 400 or documented client error;
• nonexistent resource returns 404;
• unauthorized resource returns 403 or 404 according to product rules;
• no private data is exposed;
• no stack trace appears.

8. Check invalid query parameter errors

Query parameters often control filters, sorting, pagination, and reports.

Test cases:

• unsupported filter;
• invalid filter value;
• invalid sort field;
• invalid sort direction;
• invalid page number;
• negative limit;
• limit above maximum;
• invalid date range;
• from date after to date;
• unsupported search query syntax.

Expected result:

• status is 400 or documented behavior;
• error identifies invalid parameter;
• API does not ignore dangerous invalid values silently;
• API does not return excessive data;
• no 500.

9. Check field-level validation errors

Field-level errors help client apps show useful messages.

Check that:

• error identifies exact field;
• nested field path is clear;
• array item error identifies index if useful;
• multiple field errors are returned if supported;
• message is understandable;
• machine-readable field error code exists if product uses it;
• field names match request body;
• error format is consistent across endpoints.

Example:

Response fields:

• error.code: VALIDATION_ERROR;
• error.fields[0].field: items[0].quantity;
• error.fields[0].message: Quantity must be greater than 0.;
• error.requestId: req_789;

10. Check multiple validation errors

Some APIs return one error at a time. Others return all validation errors.

Test case:

• send request with several invalid fields.

Expected result:

• behavior follows API design;
• errors are consistent;
• all returned fields are correct;
• client can display errors;
• no invalid data is saved;
• no server error.

Consistency matters most. If API sometimes returns one error and sometimes returns an array without clear rules, clients become fragile.

11. Check authentication errors: 401

Authentication errors should be clear but safe.

Test cases:

• missing token;
• invalid token;
• malformed token;
• expired token;
• revoked token;
• missing API key;
• invalid API key;
• disabled account;
• deleted account.

Expected result:

• status is 401 Unauthorized;
• protected data is not returned;
• error response follows schema;
• message does not expose sensitive details;
• token or key is not written in response;
• logs contain enough information for debugging.

Example:

Response fields:

• error.code: UNAUTHORIZED;
• error.message: Authentication is required.;
• error.requestId: req_001;

12. Check permission errors: 403

Permission errors occur when a user is authenticated but not allowed.

Test cases:

• regular user calls admin endpoint;
• read-only user tries update;
• user tries owner-only action;
• user tries manager-only action;
• user tries action in wrong workspace;
• user tries disabled feature;
• service account lacks scope.

Expected result:

• status is 403 Forbidden;
• action is not performed;
• response does not expose private data;
• error is safe and consistent;
• logs show permission failure.

Important: hidden UI buttons are not enough. Backend must return permission error.

13. Check not found errors: 404

Not found errors should be predictable and safe.

Test cases:

• nonexistent resource ID;
• deleted resource;
• hidden resource;
• resource unavailable to current user if product uses 404 to hide existence;
• wrong route;
• old endpoint removed.

Expected result:

• status is 404 Not Found;
• error follows schema;
• no stack trace;
• no private resource details;
• behavior is consistent across endpoints.

For private resources, some products use 404 instead of 403 to avoid confirming resource existence. That rule should be consistent.

14. Check conflict errors: 409

Conflict errors happen when request conflicts with current state.

Test cases:

• duplicate email;
• duplicate order number;
• creating resource that already exists;
• updating stale version;
• invalid state transition;
• concurrent update conflict;
• idempotency key conflict;
• resource already processed;
• booking slot already taken.

Expected result:

• status is 409 Conflict or documented alternative;
• error explains conflict safely;
• existing data is not corrupted;
• no duplicate record is created;
• client can understand next action.

Example:

Response fields:

• error.code: EMAIL_ALREADY_EXISTS;
• error.message: A user with this email already exists.;
• error.requestId: req_002;

15. Check unsupported method errors: 405

Unsupported HTTP methods should not create side effects.

Test cases:

• POST to read-only endpoint;
• GET to create endpoint;
• DELETE where delete is not supported;
• PATCH where only PUT is supported;
• unexpected method override header.

Expected result:

• status is 405 Method Not Allowed or documented safe error;
• no state change;
• allowed methods are not overly exposed if product avoids it;
• no server error.

16. Check unsupported content type errors: 415

Content type errors should be handled safely.

Test cases:

• send text/plain to JSON endpoint;
• send XML to JSON endpoint;
• send form data where JSON is required;
• missing Content-Type;
• invalid multipart request.

Expected result:

• status is 415 Unsupported Media Type or documented client error;
• no unsafe parsing;
• no server crash;
• no data saved.

17. Check rate limit errors: 429

Rate limit errors should protect API without confusing clients.

Test cases:

• too many login attempts;
• too many password reset requests;
• too many search requests;
• too many export requests;
• too many file upload requests;
• too many requests with same API key.

Expected result:

• status is 429 Too Many Requests;
• error follows schema;
• retry guidance is provided if supported;
• Retry-After header is returned if product uses it;
• no hidden server error;
• normal user behavior is not blocked too aggressively.

Example:

Response fields:

• error.code: RATE_LIMIT_EXCEEDED;
• error.message: Too many requests. Try again later.;
• error.requestId: req_003;

18. Check server errors: 5xx

Server errors should be rare, safe, and observable.

Test cases:

• controlled internal exception in non-production;
• database temporary failure;
• downstream unavailable;
• unexpected null state;
• internal processing error.

Expected result:

• status is 500, 502, 503, or 504 depending on scenario;
• response does not expose stack trace;
• response does not expose SQL or internal paths;
• request ID is returned;
• detailed error is logged server-side;
• monitoring captures error;
• client receives safe generic message.

Bad:

Response fields:

• message: SQLSTATE[42S02]: Base table or view not found...;

Better:

Response fields:

• error.code: INTERNAL_ERROR;
• error.message: Something went wrong. Please try again later.;
• error.requestId: req_004;

19. Check timeout errors

Timeouts should not leave users or systems in confusing states.

Test cases:

• API request times out;
• external provider times out;
• database operation times out;
• async job takes too long;
• gateway timeout occurs.

Expected result:

• timeout returns documented error;
• operation is not falsely marked successful;
• retry behavior is clear;
• duplicate record is not created after retry;
• logs show timeout reason;
• monitoring detects timeout spike;
• user/client can recover.

Dangerous case: client retries after timeout and creates duplicate order, payment, or booking.

20. Check external provider failure errors

APIs often depend on external systems.

Test cases:

• payment provider unavailable;
• CRM API returns error;
• email provider times out;
• shipping provider returns invalid address;
• identity provider unavailable;
• storage provider fails;
• analytics provider rejects request.

Expected result:

• source API does not mark operation as successful if downstream failed;
• error is logged;
• user-facing message is appropriate if needed;
• retry or recovery path exists if needed;
• no partial broken state;
• no duplicate side effect after retry.

21. Check duplicate request errors

Duplicate requests should not create unexpected duplicates.

Test cases:

• send same POST twice quickly;
• retry after timeout;
• double submit from frontend;
• repeated webhook event;
• same request from two tabs;
• duplicate import request.

Expected result:

• API prevents duplicate where required;
• returns conflict, idempotent response, or documented behavior;
• no duplicate record if business rules forbid it;
• no duplicate email/payment/order/booking is created.

22. Check idempotency conflict errors

Idempotency errors should be clear.

Test cases:

• same idempotency key with same body;
• same idempotency key with different body;
• expired idempotency key reused;
• missing idempotency key on critical endpoint;
• duplicate key under concurrent requests.

Expected result:

• same key and same body returns safe result;
• same key and different body returns conflict or documented error;
• one record is created;
• client can understand whether request succeeded or failed.

23. Check business rule errors

Some errors are not technical validation errors. They are business rules.

Test cases:

• booking slot unavailable;
• item out of stock;
• coupon expired;
• coupon not applicable;
• plan limit exceeded;
• account suspended;
• invoice already paid;
• order already canceled;
• refund window expired;
• subscription already active.

Expected result:

• status code follows product convention;
• error code reflects business rule;
• message is useful;
• no invalid state is created;
• client can show meaningful message.

Example:

Response fields:

• error.code: ITEM_OUT_OF_STOCK;
• error.message: This item is no longer available.;
• error.requestId: req_005;

24. Check partial failure handling

Partial failures are especially risky in APIs with side effects.

Examples:

• order created, but email failed;
• payment succeeded, but order status failed to update;
• lead saved internally, but CRM sync failed;
• file uploaded, but metadata failed;
• subscription activated, but notification failed.

Expected result:

• partial failure is detected;
• final state is not misleading;
• critical failure is logged;
• retry/recovery is possible;
• user-facing status is appropriate;
• no duplicate is created after retry;
• support can see what failed.

25. Check async job error handling

Async APIs need clear error behavior.

Test cases:

• job creation fails;
• job processing fails;
• job times out;
• job result expires;
• user requests job belonging to another user;
• job status endpoint receives invalid ID.

Expected result:

• job errors are visible;
• job status is clear: pending, processing, completed, failed;
• failed job has safe error reason;
• retry is available if supported;
• user cannot access another user’s job result.

26. Check webhook error handling

Webhook endpoints should handle invalid and duplicate events safely.

Test cases:

• invalid signature;
• missing signature;
• invalid payload;
• unsupported event type;
• duplicate event ID;
• out-of-order event;
• processing failure;
• retry after temporary failure.

Expected result:

• invalid signature is rejected;
• unsupported event is handled safely;
• duplicate event is not processed twice;
• failed processing is logged;
• retry works if expected;
• final business state is correct.

27. Check file upload error handling

File upload APIs need specific error cases.

Test cases:

• unsupported file type;
• file too large;
• empty file;
• corrupted file;
• wrong content type;
• missing file;
• user without permission;
• storage failure;
• virus scan failure if applicable.

Expected result:

• safe client error;
• no broken file record;
• no unsafe file stored;
• no stack trace;
• logs contain enough debug info.

28. Check file download error handling

Download APIs should fail safely.

Test cases:

• file not found;
• file deleted;
• file belongs to another user;
• signed URL expired;
• storage provider unavailable;
• invalid file ID.

Expected result:

• proper error status;
• file content is not exposed;
• error response is safe;
• logs are useful;
• user can retry if temporary failure.

29. Check pagination and filtering errors

List endpoints can fail in subtle ways.

Test cases:

• invalid page;
• invalid cursor;
• expired cursor;
• limit above maximum;
• unsupported filter;
• invalid date range;
• invalid sort field;
• filter on private/internal field.

Expected result:

• safe client error;
• no excessive data returned;
• no private data exposed;
• no server error.

30. Check search error handling

Search endpoints should handle edge cases safely.

Test cases:

• empty query;
• very long query;
• special characters;
• unsupported syntax;
• search backend unavailable;
• timeout from search provider.

Expected result:

• behavior follows product rules;
• user/client receives safe message;
• no raw search engine error exposed;
• fallback or retry path exists if needed.

31. Check safe error messages

Error messages should be helpful but not dangerous.

Check that error messages:

• explain what client can fix;
• avoid internal service names;
• avoid SQL details;
• avoid stack traces;
• avoid secrets;
• avoid full tokens;
• avoid full payment data;
• avoid private resource details;
• avoid confirming sensitive account existence if product requires privacy;
• use consistent language and tone.

Good:

Response fields:

• code: INVALID_DATE_RANGE;
• message: The start date must be before the end date.;

Bad:

Response fields:

• message: ReportService failed: invalid PostgreSQL query at line 38;

32. Check request ID and correlation ID

Request IDs make error investigation much easier.

Check that:

• request ID is returned in error response;
• same request ID appears in logs;
• correlation ID passes through services if supported;
• external provider error is linked to internal request ID if possible;
• request ID is not guessable in a harmful way;
• support can search by request ID;
• request ID is included in monitoring/alerting.

Without request ID, support and engineering waste time matching timestamps manually.

33. Check logs for API errors

Errors should be logged with enough context.

Check that logs include:

• endpoint;
• method;
• status code;
• error code;
• request ID;
• user/client ID where safe;
• tenant/workspace ID where safe;
• validation failure details;
• downstream provider error;
• retry count if applicable;
• stack trace server-side if allowed internally;
• timestamp;
• environment.

Check that logs do not include:

• passwords;
• full tokens;
• API keys;
• secrets;
• full card numbers;
• unnecessary PII;
• raw sensitive payload unless access-controlled.

34. Check monitoring and alerts for errors

Monitoring should show error patterns, not only individual failures.

Check that:

• 4xx rate is tracked;
• 5xx rate is tracked;
• validation error spike is visible;
• auth error spike is visible;
• permission error spike is visible;
• rate limit spike is visible;
• timeout spike is visible;
• external provider errors are visible;
• error dashboard exists;
• alerts are configured for critical error rates;
• alert goes to correct team.

API error handling is not complete if nobody can see that errors increased after release.

35. Check API documentation for errors

If API is public, partner-facing, or used by multiple teams, errors should be documented.

Check docs for:

• common error codes;
• status codes;
• error response schema;
• validation error examples;
• authentication error example;
• permission error example;
• not found example;
• conflict example;
• rate limit example;
• idempotency conflict example;
• retry guidance;
• troubleshooting guidance.

Docs should help API consumers handle errors correctly without asking the team every time.

36. Check frontend/mobile handling of API errors

API error handling affects clients.

Check that:

• frontend can parse error response;
• mobile app can parse error response;
• field-level errors are shown near correct fields;
• auth error redirects or refreshes token correctly;
• permission error is shown safely;
• rate limit error is shown clearly;
• server error shows generic retry message;
• request ID can be shown to support if useful;
• client does not crash on unexpected error format;
• client does not expose raw technical errors to users.

Even perfect API errors are useless if clients cannot handle them.

37. Check integration handling of API errors

API errors should be usable by other systems.

Check that:

• external client can distinguish validation vs retryable failure;
• integration can retry temporary errors;
• integration does not retry permanent validation errors endlessly;
• integration logs error code;
• integration stores failed payload safely;
• integration does not mark failed operation as success;
• integration can recover after provider/API failure;
• duplicate prevention works after retry.

This is especially important for partner APIs, payment APIs, CRM sync, ERP sync, webhooks, and imports.

38. Check production-safe error smoke after release

After deployment, run a short safe error smoke if approved.

Check non-destructive cases:

• protected endpoint without token returns 401;
• invalid token returns 401;
• regular user on safe forbidden endpoint returns 403;
• nonexistent safe test resource returns 404;
• invalid validation request returns 400;
• unsupported method returns safe error;
• response includes request ID;
• no stack trace is exposed;
• logs contain request ID;
• monitoring remains stable.

Production error smoke should be safe, limited, and agreed with the team.

39. Run error regression after fixes

When an error handling bug is fixed, add regression coverage.

Check that:

• original bug is fixed;
• similar endpoint is checked;
• same error type is checked across related endpoints;
• frontend/mobile still handles error;
• logs are still useful;
• no new security leak appears;
• automated test is added if possible;
• documentation is updated if public behavior changed.

Example: if invalid JSON returned 500 on one endpoint, check other JSON endpoints too.

40. Document API error handling test result

After testing, document the result.

Include:

• environment;
• API version;
• endpoints tested;
• error categories tested;
• status codes observed;
• error schema result;
• unsafe messages found;
• sensitive data leaks found;
• logs/monitoring result;
• client handling result if tested;
• issues created;
• remaining risks;
• pass/fail decision.

Good error handling bugs need exact request, response, status code, request ID, and logs reference.

Common mistakes

1. Treating error handling as secondary

Errors are part of the API contract. Clients depend on them as much as success responses.

2. Returning 500 for client mistakes

Missing field, invalid JSON, invalid enum, and invalid parameter should usually be client errors, not server errors.

3. Using inconsistent error formats

If every endpoint returns a different error shape, clients become fragile and hard to maintain.

4. Not returning field-level validation errors

Without field-level errors, frontend and mobile apps cannot show useful form messages.

5. Leaking stack traces or SQL details

Error messages should not expose internal implementation, file paths, SQL queries, service names, tokens, or secrets.

6. Not including request ID

Without request ID, support and engineering cannot quickly connect user reports to logs.

7. Retrying non-retryable errors

Validation errors should not be retried endlessly by integrations or background jobs.

8. Marking failed downstream operation as success

If CRM, payment provider, email provider, or ERP failed, the API should not pretend that the full operation succeeded.

9. Not testing client behavior

API error response may be correct, but frontend/mobile/integration clients may still fail to parse it.

10. Not adding regression tests

Error handling bugs often return. Add regression tests for fixed error cases.

FAQ

What is an API Error Handling Testing Checklist?

An API Error Handling Testing Checklist is a focused checklist for testing how an API responds to error conditions.

It covers validation errors, authentication failures, permission problems, missing resources, conflicts, rate limits, timeouts, external provider failures, server errors, error response schema, safe messages, logs, monitoring, and production-safe error smoke.

How is API error handling testing different from API testing?

API testing checks whether endpoints work correctly overall.

API error handling testing checks only error behavior: whether the API returns clear, safe, consistent, and useful errors when something goes wrong.

What should a good API error response include?

A good API error response often includes:

• machine-readable error code;
• human-readable message;
• field name for validation errors;
• request ID or correlation ID;
• safe status code;
• no stack trace;
• no secrets;
• no internal implementation details.

What is a good API error response example?

Example:

Response fields:

• error.code: VALIDATION_ERROR;
• error.message: Email is required.;
• error.field: email;
• error.requestId: req_123;

This response is clear, structured, field-specific, and safe.

What status codes should be tested for API errors?

Common API error status codes to test include:

• 400 for bad request or validation errors;
• 401 for unauthenticated requests;
• 403 for forbidden actions;
• 404 for missing resources;
• 405 for unsupported methods;
• 409 for conflicts;
• 415 for unsupported media type;
• 429 for rate limits;
• 500, 502, 503, 504 for server or upstream failures.

How do you test API validation errors?

Send requests with:

• missing required fields;
• invalid data types;
• invalid formats;
• invalid enum values;
• too-long strings;
• negative numbers;
• invalid nested objects;
• invalid arrays.

Expected result: API returns safe 400 response with clear field-level errors and does not create or modify data.

How do you test API authentication errors?

Send requests with:

• no token;
• invalid token;
• expired token;
• malformed token;
• revoked token;
• missing API key;
• invalid API key.

Expected result: API returns 401, does not expose protected data, and does not leak token details.

How do you test API permission errors?

Use a valid authenticated user without permission.

Examples:

• regular user calls admin endpoint;
• User A requests User B resource;
• read-only user tries update;
• tenant A user accesses tenant B data.

Expected result: API returns 403 or 404 according to product rules and does not expose private data.

How do you test API conflict errors?

Test cases include:

• duplicate email;
• duplicate order;
• stale update;
• already paid invoice;
• already canceled order;
• idempotency key conflict;
• booking slot already taken.

Expected result: API returns 409 or documented conflict error, with clear message and no corrupted data.

How do you test API rate limit errors?

Send repeated requests to a rate-limited endpoint.

Expected result: API returns 429, provides retry guidance if supported, logs the event, and does not block normal usage too aggressively.

How do you test API server error handling?

In a controlled environment, simulate internal failure or downstream failure.

Expected result: API returns safe 5xx response, includes request ID, logs detailed server-side error, and does not expose stack trace or secrets to client.

How do you know API error handling passed?

API error handling can be considered passed when:

• invalid requests return correct client errors;
• auth failures return 401;
• permission failures return 403 or safe 404;
• conflicts are handled clearly;
• rate limits return 429;
• server errors are safe;
• error response schema is consistent;
• field-level errors are useful;
• request ID is available;
• logs and monitoring work;
• no sensitive data or internals are exposed;
• clients can parse and handle errors correctly.