A provider compatibility problem occurs when an AI provider’s documented behavior, advertised capabilities, or model support differs from the API’s actual implementation. These mismatches can break otherwise normal application flows. section 8.2.1
Typical compatibility failures include:
- Unannounced API changes, unclear regional restrictions, documentation-to-implementation gaps, and inconsistent behavior across model versions. section 8.2.1
- Capability mismatches involving image analysis, audio transcription, function calling, or streaming responses. section 8.2.1
- Runtime symptoms such as empty responses, inconsistent token limits, and unclear content-policy errors. section 8.2.1
Make failures recoverable
Wrap provider calls in robust error handling, record the provider, model, and input, then return a user-facing error with a request ID and retry action. section 8.2.1
Listing 8.2 Integrating error tracking into the application
import { AIErrorTracker } from '@/lib/error-tracking'; #1
export async function continueConversation(input, provider, model) {
...
} catch (error) {
const errorData =
await AIErrorTracker.trackError(error, { #2
provider,
model,
input,
});
const userError =
AIErrorTracker.createUserFacingError(errorData); #3
return {
id: userError.requestId,
role: 'assistant',
display: ( #4
<ChatBubble
role="error"
text={`${userError.message} (Request ID: ${userError.requestId})`}
className="mr-auto border-none error"
/>
),
};
}
Use the error-tracking implementation to connect provider failures with diagnostics and recoverable chat responses. section 8.2.1
