ERROR HANDLING
An empty result is not
a failed request.
Define outcomes before retry logic. Preserve what happened and make the effect on the observation visible.
A proposed outcome model
Map real provider responses into explicit application states. The labels below are design suggestions, not status codes returned by a live SearchEngineaAPI.com service.
| Outcome | Interpretation | Next step |
|---|---|---|
| Completed with results | The response passed validation and contains records. | Publish with the original source and observation time. |
| Completed without results | A valid, completed query returned an empty result set. | Display an empty result state without inventing missing values. |
| Invalid request | The request does not fit the provider contract. | Correct the request before sending it again. |
| Authentication failure | The supplied credentials were not accepted. | Pause the job and review credential handling. Do not expose secrets. |
| Temporarily unavailable | The source could not complete the operation. | Follow documented retry semantics within a finite budget. |
| Timed out | The local deadline elapsed; remote completion may be unknown. | Check safe retry or task-status semantics before repeating work. |
| Malformed response | The body could not be interpreted under the expected contract. | Quarantine the record and review a permitted diagnostic fixture. |
| Unsupported context | The requested setting is not supported or confirmed. | Explain the limitation; do not silently substitute a different context. |
Protect the meaning of cached data
A cached response keeps its original observation time. When a refresh fails, label the prior observation as old instead of presenting it as newly measured. Include all context dimensions that affect the observation in your cache key.
Bound repeated attempts
Give an operation a deadline and a maximum attempt count. Understand whether retrying can create another billable task or side effect. Assign one layer to own the retry policy so nested retries do not unexpectedly multiply work.
Test locally first
Use fixtures for empty arrays, missing optional fields, invalid content types, and failed states. Check both the parser and the user-facing label. An interface that keeps rendering incorrect data is not more reliable because it hides the error.