Postconditions: what we check

• complete · complete-no-error-handling

  error
  Whenclient.chat.complete() or client.fim.complete() called without try-catch or .catch() handler
  ThrowsSDKError (base class for all HTTP errors). RateLimitError (429 — too many requests). UnauthorizedError (401 — invalid API key). BadRequestError (400 — invalid parameters, unsupported model). ServiceUnavailableError (503) / GatewayTimeoutError (504). SDKValidationError (response schema mismatch). Network errors: ECONNREFUSED, ETIMEDOUT.
  Required handlingCaller MUST wrap await client.chat.complete() in try-catch or chain .catch(). Uncaught error causes unhandled promise rejection — API routes return 500, chatbot UIs show blank screens, completions silently fail. try { const response = await client.chat.complete({ model: 'mistral-large-latest', messages: [{ role: 'user', content: 'Hello' }], }); return response.choices[0].message.content; } catch (error) { console.error('Mistral API error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• stream · stream-no-error-handling

  error
  Whenclient.chat.stream() called without try-catch or .catch() handler
  ThrowsSame error types as complete() — thrown before streaming begins. Network errors can also throw mid-stream during iteration.
  Required handlingCaller MUST wrap await client.chat.stream() in try-catch or chain .catch(). Also consider try-catch around the async iteration loop to handle mid-stream errors. try { const stream = await client.chat.stream({ model: 'mistral-large-latest', messages: [{ role: 'user', content: 'Hello' }], }); for await (const chunk of stream) { yield chunk.data.choices[0]?.delta?.content ?? ''; } } catch (error) { console.error('Mistral stream error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][2]
• create · embeddings-create-no-error-handling

  error
  Whenclient.embeddings.create() called without try-catch or .catch() handler
  ThrowsMistralError (base, .statusCode populated) for all HTTP error responses. HTTPValidationError (.statusCode=422, .detail[] array) for invalid inputs. SDKError for unmatched status codes or unexpected content types. ConnectionError when network is unreachable. RequestTimeoutError when request exceeds configured timeout. SDKValidationError when input fails SDK schema validation before request. Note: 429 rate limit is auto-retried by SDK before throwing.
  Required handlingCaller MUST wrap await client.embeddings.create() in try-catch or chain .catch(). RAG pipelines and embedding jobs often run in background tasks or loops — uncaught errors silently halt the entire ingestion pipeline. Search quality degrades to zero without alerting. try { const response = await client.embeddings.create({ model: 'mistral-embed', inputs: ['Hello world', 'Another document'], }); return response.data.map(e => e.embedding); } catch (error) { console.error('Mistral embeddings error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[4][5]
• process · ocr-process-no-error-handling

  error
  Whenclient.ocr.process() called without try-catch or .catch() handler
  ThrowsHTTPValidationError (.statusCode=422) when document URL is invalid, base64 encoding is malformed, or document format is unsupported. MistralError when API key is invalid (401), quota exhausted, or server fails. ConnectionError on network failures. RequestTimeoutError if document processing exceeds timeout (large documents).
  Required handlingCaller MUST wrap await client.ocr.process() in try-catch or chain .catch(). Document processing pipelines often handle user-uploaded content — invalid PDFs or unsupported formats throw HTTPValidationError (422) which must be caught and returned as a user-readable error, not a 500. try { const result = await client.ocr.process({ model: 'mistral-ocr-latest', document: { type: 'document_url', documentUrl: 'https://example.com/document.pdf', }, }); return result.pages.map(p => p.markdown).join('\n'); } catch (error) { if (error instanceof HTTPValidationError) { throw new Error('Invalid document format or URL'); } throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][7]
• upload · files-upload-no-error-handling

  error
  Whenclient.files.upload() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=413) when file exceeds 512 MB size limit. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=422) for invalid file format (e.g. non-JSONL for fine-tuning). ConnectionError / RequestTimeoutError for large file uploads that timeout. SDKValidationError when request object fails SDK schema validation.
  Required handlingCaller MUST wrap await client.files.upload() in try-catch or chain .catch(). File uploads are commonly used in fine-tuning prep workflows or batch pipelines — uncaught size limit errors (413) cause the entire workflow to crash before any fine-tuning is enqueued. try { const fileObj = await client.files.upload({ file: { name: 'training_data.jsonl', data: fileBlob }, purpose: 'fine-tune', }); return fileObj.id; } catch (error) { console.error('Mistral file upload error:', error); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[8]
• complete · agents-complete-no-error-handling

  error
  Whenclient.agents.complete() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when agentId does not exist or is deleted. HTTPValidationError (.statusCode=422) when messages array is malformed. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — SDK auto-retries before throwing. ConnectionError / RequestTimeoutError on network failures.
  Required handlingCaller MUST wrap await client.agents.complete() in try-catch or chain .catch(). Agent IDs can be revoked or deleted — uncaught 404 MistralError crashes the request handler, returning 500 to users. Agent IDs should be validated at startup. try { const response = await client.agents.complete({ agentId: process.env.MISTRAL_AGENT_ID, messages: [{ role: 'user', content: userMessage }], }); return response.choices[0].message.content; } catch (error) { console.error('Mistral agent error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• complete · audio-transcriptions-no-error-handling

  error
  Whenclient.audio.transcriptions.complete() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=422) for unsupported audio format or corrupted file. MistralError (.statusCode=413) if audio file exceeds size limit. MistralError (.statusCode=401) when API key is invalid. ConnectionError when network is unreachable during multipart upload. RequestTimeoutError for long audio files that exceed timeout.
  Required handlingCaller MUST wrap await client.audio.transcriptions.complete() in try-catch. Voice input features in production apps throw on unsupported audio formats — browsers may send audio in formats the API does not accept (e.g. WEBM without proper codec tags). Uncaught errors crash the voice pipeline silently. try { const result = await client.audio.transcriptions.complete({ model: 'voxtlite-2506', file: audioBlob, }); return result.text; } catch (error) { console.error('Mistral transcription error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• complete · audio-speech-no-error-handling

  error
  Whenclient.audio.speech.complete() called without try-catch or .catch() handler
  ThrowsHTTPValidationError (.statusCode=422) for invalid voice name or input text that exceeds character limits. MistralError (.statusCode=401) when API key is invalid. MistralError for other 4XX/5XX responses. ConnectionError when streaming audio response fails mid-download.
  Required handlingCaller MUST wrap await client.audio.speech.complete() in try-catch or chain .catch(). Text-to-speech features in production apps use voice IDs that can be invalidated — uncaught HTTPValidationError (422) crashes the TTS pipeline. try { const audio = await client.audio.speech.complete({ model: 'mistral-voice-latest', input: 'Hello, how can I help you today?', voice: 'af_sky', }); return audio; } catch (error) { console.error('Mistral speech error:', error); throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[11]
• complete · fim-complete-no-error-handling

  error
  Whenclient.fim.complete() called without try-catch or .catch() handler
  ThrowsMistralError for all HTTP errors (401 invalid key, 422 invalid params, 4XX/5XX). HTTPValidationError (.statusCode=422) for malformed prompt/suffix. ConnectionError / RequestTimeoutError on network failures. SDKValidationError when input fails schema validation before request.
  Required handlingCaller MUST wrap await client.fim.complete() in try-catch or chain .catch(). Code autocomplete features are latency-sensitive — uncaught errors disable the autocomplete feature entirely for affected users. try { const response = await client.fim.complete({ model: 'codestral-latest', prompt: 'def fibonacci(n):', suffix: '\n return result', }); return response.choices[0].message.content; } catch (error) { console.error('Mistral FIM error:', error); throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[12][13]
• moderate · classifiers-moderate-no-error-handling

  error
  Whenclient.classifiers.moderate() or client.classifiers.moderateChat() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=401) when API key is invalid. HTTPValidationError (.statusCode=422) for malformed inputs array or invalid classifier model. MistralError for other 4XX/5XX server errors. ConnectionError on network failures.
  Required handlingCaller MUST wrap await client.classifiers.moderate() in try-catch or chain .catch(). Content moderation is a safety-critical pipeline — uncaught errors may cause unmoderated content to pass through if the catch path allows through on failure. Always fail closed: if moderation throws, reject the content. try { const result = await client.classifiers.moderate({ model: 'mistral-moderation-latest', inputs: [{ text: userContent }], }); const isViolation = result.results[0].categories['hate']; return isViolation; } catch (error) { console.error('Mistral moderation error:', error); // Fail closed: reject content if moderation is unavailable return true; }
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[14][15]
• create · batch-jobs-create-no-error-handling

  error
  Whenclient.batch.jobs.create() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when inputFiles contain invalid or deleted file IDs. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=422) for malformed request (invalid endpoint or metadata). MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError / RequestTimeoutError on network failures.
  Required handlingCaller MUST wrap await client.batch.jobs.create() in try-catch or chain .catch(). Batch jobs are used in document processing and large-scale inference pipelines — uncaught errors during job creation cause the entire batch to be silently dropped. Additionally, a successfully created job with status FAILED must be checked separately via batch.jobs.get() — this postcondition only covers the creation throw. try { const job = await client.batch.jobs.create({ model: 'mistral-large-latest', inputFiles: [uploadedFileId], endpoint: '/v1/chat/completions', metadata: { jobName: 'nightly-batch' }, }); console.log(`Batch job created: ${job.id}, status: ${job.status}`); return job.id; } catch (error) { console.error('Mistral batch job creation error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[16][17]
• start · conversations-start-no-error-handling

  error
  Whenclient.beta.conversations.start() called without try-catch or .catch() handler
  ThrowsHTTPValidationError (.statusCode=422, .detail[] array) when inputs array is malformed, message format is invalid, or conversation parameters fail validation. MistralError (.statusCode=404) when agentId does not exist or has been deleted. MistralError (.statusCode=401) when API key is invalid or missing. MistralError for other 4XX/5XX responses (quota exhausted, server error). 429 rate limit is auto-retried by SDK before throwing. ConnectionError when network is unreachable. RequestTimeoutError when request exceeds configured timeout (default 30s). SDKValidationError when request object fails schema validation before sending.
  Required handlingCaller MUST wrap await client.beta.conversations.start() in try-catch or chain .catch(). Chatbot features in SaaS apps create conversations on every new session — uncaught errors (invalid agentId, API key revoked) cause entire chat features to fail silently, returning 500 to users. The conversation_id from the response MUST be persisted for subsequent append() calls. try { const response = await client.beta.conversations.start({ model: 'mistral-large-latest', inputs: [{ role: 'user', content: 'Hello' }], }); const conversationId = response.conversationId; return { conversationId, reply: response.outputs[0]?.content }; } catch (error) { console.error('Mistral conversation start error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18][19]
• append · conversations-append-no-error-handling

  error
  Whenclient.beta.conversations.append() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when conversationId does not exist, has been deleted, or belongs to a different API key / workspace. HTTPValidationError (.statusCode=422) when inputs are malformed or conversationId path parameter is invalid format. MistralError (.statusCode=401) when API key is invalid. MistralError for other 4XX/5XX server errors. ConnectionError when network is unreachable. RequestTimeoutError when long conversations exceed the 30s default timeout.
  Required handlingCaller MUST wrap await client.beta.conversations.append() in try-catch or chain .catch(). Multi-turn chat apps call append() on every user message — an expired conversationId (404) must be caught and handled by creating a new conversation rather than propagating a 500 to the user. Long conversations may hit token limits (422) that need graceful user-facing error messages. try { const response = await client.beta.conversations.append({ conversationId: session.mistralConversationId, conversationAppendRequest: { inputs: [{ role: 'user', content: userMessage }], }, }); return response.outputs[0]?.content ?? ''; } catch (error) { if (error instanceof MistralError && error.statusCode === 404) { // Conversation expired — restart throw new Error('Conversation session expired, please start a new chat'); } console.error('Mistral conversation append error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20][21]
• executeWorkflow · workflows-execute-no-error-handling

  error
  Whenclient.workflows.executeWorkflow() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when workflowIdentifier does not exist or has been archived. HTTPValidationError (.statusCode=422) when input parameters fail workflow schema validation or required workflow inputs are missing. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError when network is unreachable. RequestTimeoutError when workflow execution exceeds configured timeout.
  Required handlingCaller MUST wrap await client.workflows.executeWorkflow() in try-catch or chain .catch(). AI workflows are often integrated into user-facing product features (document processing, agentic operations) — uncaught errors from invalid workflow identifiers or archived workflows crash the entire request handler, returning 500 to users. Workflow identifiers should be validated at startup or wrapped with fallback logic. try { const result = await client.workflows.executeWorkflow({ workflowIdentifier: process.env.MISTRAL_WORKFLOW_ID, workflowExecutionRequest: { inputs: { document: userDocument }, }, }); return result; } catch (error) { console.error('Mistral workflow execution error:', error); throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22][23]
• create · libraries-create-no-error-handling

  error
  Whenclient.beta.libraries.create() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=401) when API key is invalid or missing. HTTPValidationError (.statusCode=422) when library name is missing, too long, or embeddingModel is not supported. MistralError (.statusCode=409) for duplicate library name within the same workspace. MistralError for quota exhaustion or server errors. ConnectionError / RequestTimeoutError on network failures.
  Required handlingCaller MUST wrap await client.beta.libraries.create() in try-catch or chain .catch(). Library creation is typically part of an onboarding flow or document pipeline setup — uncaught 409 errors (duplicate name) crash the setup workflow instead of providing a user-friendly "library already exists" message. try { const library = await client.beta.libraries.create({ name: 'product-docs', description: 'Product documentation for RAG', }); return library.id; } catch (error) { console.error('Mistral library creation error:', error); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24][25]
• upload · libraries-documents-upload-no-error-handling

  error
  Whenclient.beta.libraries.documents.upload() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when libraryId does not exist or has been deleted. HTTPValidationError (.statusCode=422) when file format is unsupported, document metadata fails validation, or required fields are missing. MistralError (.statusCode=413) when document file exceeds size limits. MistralError (.statusCode=401) when API key is invalid. ConnectionError / RequestTimeoutError for large file uploads that timeout. SDKValidationError when request object fails schema validation.
  Required handlingCaller MUST wrap await client.beta.libraries.documents.upload() in try-catch or chain .catch(). Document upload is the key ingestion step for RAG pipelines — an invalid libraryId (404, e.g. library was deleted) causes the entire ingestion batch to fail silently if uncaught. Upload does NOT mean the document is immediately searchable; the document status must be polled to confirm processing completion. try { const doc = await client.beta.libraries.documents.upload({ libraryId: process.env.MISTRAL_LIBRARY_ID, file: documentBlob, name: 'user-guide.pdf', }); // Document is now queued — poll doc.status for "processed" return doc.id; } catch (error) { if (error instanceof HTTPValidationError) { throw new Error('Unsupported document format'); } console.error('Mistral library document upload error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[26][27]
• classify · classifiers-classify-no-error-handling

  error
  Whenclient.classifiers.classify() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when model ID does not exist or is not a fine-tuned classifier model accessible to this API key. HTTPValidationError (.statusCode=422) when inputs are malformed or empty, or model is not a valid classifier (wrong model type). MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError when network is unreachable. RequestTimeoutError when batch classification exceeds timeout.
  Required handlingCaller MUST wrap await client.classifiers.classify() in try-catch or chain .catch(). Custom classifiers are used in routing and triage pipelines — uncaught errors from a deleted or unavailable classifier model halt request routing entirely, causing all traffic to be misrouted or dropped. Classifier model IDs should be validated at startup with fallback routing logic. try { const result = await client.classifiers.classify({ model: process.env.MISTRAL_CLASSIFIER_MODEL_ID, inputs: [userMessage], }); const topCategory = result.data[0]?.results[0]?.name; return topCategory; } catch (error) { console.error('Mistral classifier error:', error); // Fall back to default routing return 'general'; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[28][29]
• create · fine-tuning-jobs-create-no-error-handling

  error
  Whenclient.fine_tuning.jobs.create() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when any training file ID in trainingFiles does not exist or was deleted. MistralError (.statusCode=422) when model is not fine-tuneable, hyperparameters are invalid, or invalidSampleSkipPercentage is out of range. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError / RequestTimeoutError on network failures. SDKValidationError when request object fails schema validation before sending. Note: A successful response returns a job object with status QUEUED — this does NOT mean training has started. Job must be explicitly started when autoStart=false.
  Required handlingCaller MUST wrap await client.fineTuning.jobs.create() in try-catch or chain .catch(). SaaS platforms automating fine-tuning pipelines call this after files.upload() — an invalid file ID (404, e.g. file expired before job creation) crashes the pipeline silently if uncaught. When autoStart=false, the caller must also call fineTuning.jobs.start() after validation completes. try { const job = await client.fineTuning.jobs.create({ model: 'open-mistral-7b', trainingFiles: [{ fileId: uploadedFileId }], hyperparameters: { trainingSteps: 10, learningRate: 0.0001 }, }); console.log(`Fine-tuning job created: ${job.id}, status: ${job.status}`); return job.id; } catch (error) { console.error('Fine-tuning job creation error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[30][31]
• start · fine-tuning-jobs-start-no-error-handling

  error
  Whenclient.fine_tuning.jobs.start() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when jobId does not exist or has been deleted. MistralError (.statusCode=422) when job is not in VALIDATED state — calling start() on a job that is still VALIDATING or FAILED_VALIDATION returns 422. MistralError (.statusCode=401) when API key is invalid. ConnectionError / RequestTimeoutError on network failures. SDKValidationError when request object fails schema validation.
  Required handlingCaller MUST wrap await client.fineTuning.jobs.start() in try-catch or chain .catch(). SaaS pipelines that poll job status before calling start() still need error handling — a race condition where the job moves to FAILED_VALIDATION between status check and start() call throws 422. Always handle the 422 case with a clear error message. try { const job = await client.fineTuning.jobs.start({ jobId: fineTuningJobId, }); console.log(`Fine-tuning job started: ${job.id}, status: ${job.status}`); return job.id; } catch (error) { if (error instanceof MistralError && error.statusCode === 422) { throw new Error('Job is not in VALIDATED state — cannot start yet'); } console.error('Fine-tuning job start error:', error); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[32][33]
• callTool · connectors-call-tool-no-error-handling

  error
  Whenclient.beta.connectors.callTool() called without try-catch or .catch() handler
  ThrowsMistralError (.statusCode=404) when connectorIdOrName does not exist or the toolName is not registered on that connector. HTTPValidationError (.statusCode=422, .detail[] array) when connectorCallToolRequest parameters fail validation for the given tool schema. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError when the MCP connector's underlying service is unreachable. RequestTimeoutError when the tool execution exceeds the configured timeout.
  Required handlingCaller MUST wrap await client.beta.connectors.callTool() in try-catch or chain .catch(). Agent pipelines that call external tools (database queries, API calls) via MCP connectors throw on connector unavailability or tool schema mismatches — uncaught errors crash the entire agent step, aborting the agentic workflow. Note: A successful response may still contain tool errors via response.metadata.isError — always check metadata in addition to catching thrown errors. try { const result = await client.beta.connectors.callTool({ connectorIdOrName: process.env.MISTRAL_CONNECTOR_ID, toolName: 'query_database', connectorCallToolRequest: { arguments: { query: 'SELECT * FROM users LIMIT 10' }, }, }); // Check for tool-level errors in metadata if (result.metadata?.isError) { throw new Error(`Tool execution failed: ${result.content[0]?.text}`); } return result.content; } catch (error) { console.error('MCP connector tool call error:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[34][35]
• judgeConversation · judge-conversation-no-error-handling

  error
  Whenclient.beta.observability.judges.judgeConversation() called without try-catch or .catch() handler
  ThrowsObservabilityError (.detail.errorCode === 'JUDGE_NOT_FOUND', HTTP 404) when the judgeId does not exist or was deleted after the evaluation pipeline was configured. ObservabilityError (.detail.errorCode === 'JUDGE_CONVERSATION_FORMAT_ERROR', HTTP 422) when the messages array structure does not match the judge's expected conversation format. ObservabilityError (.detail.errorCode === 'JUDGE_MISTRAL_API_ERROR', HTTP 400) when the underlying Mistral model call within the judge fails (e.g. model unavailable, invalid messages content, context length exceeded for the judge's model). ObservabilityError (.detail.errorCode === 'JUDGE_MISTRAL_API_TIMEOUT', HTTP 408) when the underlying Mistral model call exceeds the configured timeout. MistralError (.statusCode=401) when API key is invalid or revoked. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError / RequestTimeoutError on network failures. SDKValidationError when request fails schema validation before sending. Note: ObservabilityError has a .detail field with { message: string, errorCode: string } for structured error handling — catch separately from generic MistralError.
  Required handlingCaller MUST wrap await client.beta.observability.judges.judgeConversation() in try-catch or chain .catch(). LLM-as-judge pipelines that score responses at inference time will throw ObservabilityError when the judge model times out or the conversation format is wrong — uncaught errors abort the entire scoring batch. ObservabilityError must be caught separately from MistralError because its .detail field provides structured error codes that allow differentiated handling. try { const result = await client.beta.observability.judges.judgeConversation({ judgeId: process.env.MISTRAL_JUDGE_ID, judgeConversationRequest: { messages: [ { role: 'user', content: userQuery }, { role: 'assistant', content: modelResponse }, ], properties: { expectedAnswer: groundTruth }, }, }); // answer is string | number — check type before using const score = typeof result.answer === 'number' ? result.answer : parseFloat(result.answer); return { score, analysis: result.analysis }; } catch (error) { if (error instanceof ObservabilityError) { if (error.detail?.errorCode === 'JUDGE_NOT_FOUND') { throw new Error(`Judge ${judgeId} not found — check judge ID configuration`); } if (error.detail?.errorCode === 'JUDGE_MISTRAL_API_TIMEOUT') { throw new Error(`Judge timed out — retry or use a faster judge model`); } throw new Error(`Judge error: ${error.detail?.message}`); } throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[36][37][38]
• judgeEvent · judge-event-no-error-handling

  error
  Whenclient.beta.observability.chatCompletionEvents.judge() called without try-catch or .catch() handler
  ThrowsObservabilityError (.detail.errorCode === 'JUDGE_NOT_FOUND', HTTP 404) when judgeId does not exist or was deleted after the evaluation pipeline was configured. ObservabilityError (.detail.errorCode === 'SEARCH_NOT_FOUND' or HTTP 404) when the eventId does not exist in the observability store (event expired or never logged). ObservabilityError (.detail.errorCode === 'JUDGE_MISTRAL_API_ERROR', HTTP 400) when the underlying Mistral model call within the judge fails. ObservabilityError (.detail.errorCode === 'JUDGE_MISTRAL_API_TIMEOUT', HTTP 408) when the judge model call exceeds timeout. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError / RequestTimeoutError on network failures. SDKValidationError when request fails schema validation.
  Required handlingCaller MUST wrap await client.beta.observability.chatCompletionEvents.judge() in try-catch or chain .catch(). Automated evaluation pipelines that process stored events in batches will throw ObservabilityError when any event is not found or the judge model times out — uncaught errors abort the entire batch, losing scoring progress for previously processed events in the same run. try { const result = await client.beta.observability.chatCompletionEvents.judge({ eventId: chatEventId, judgeId: process.env.MISTRAL_JUDGE_ID, }); return { score: result.answer, analysis: result.analysis }; } catch (error) { if (error instanceof ObservabilityError) { const code = error.detail?.errorCode; if (code === 'JUDGE_NOT_FOUND') { throw new Error(`Judge not found — check judge configuration`); } if (code === 'JUDGE_MISTRAL_API_TIMEOUT') { // Retry with backoff or skip this event console.warn(`Judge timed out for event ${eventId}`); return null; } throw new Error(`Observability error: ${error.detail?.message}`); } throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[39][37][38]
• judge · judge-dataset-record-no-error-handling

  error
  Whenclient.beta.observability.datasets.records.judge() called without try-catch or .catch() handler
  ThrowsObservabilityError (.detail.errorCode === 'JUDGE_NOT_FOUND', HTTP 404) when the judgeId does not exist or was deleted after the evaluation pipeline was configured. ObservabilityError (.detail.errorCode === 'DATASET_RECORD_NOT_FOUND', HTTP 404) when the datasetRecordId does not exist (record deleted, dataset pruned, or wrong ID). ObservabilityError (.detail.errorCode === 'DATASET_RECORD_FORMAT_ERROR', HTTP 422) when the dataset record's conversation format is incompatible with the judge's expected input schema — e.g., judge expects Q&A format but record is plain text. ObservabilityError (.detail.errorCode === 'JUDGE_MISTRAL_API_ERROR', HTTP 400) when the underlying Mistral model call within the judge fails. ObservabilityError (.detail.errorCode === 'JUDGE_MISTRAL_API_TIMEOUT', HTTP 408) when the judge model call exceeds the evaluation timeout. MistralError (.statusCode=401) when API key is invalid. MistralError (.statusCode=429) rate limit — auto-retried by SDK before throwing. ConnectionError / RequestTimeoutError on network failures. SDKValidationError when request fails schema validation.
  Required handlingCaller MUST wrap await client.beta.observability.datasets.records.judge() in try-catch or chain .catch(). Automated evaluation pipelines that batch-score dataset records will throw ObservabilityError when any record is missing or the judge model times out — uncaught errors abort the entire batch, losing scoring progress for all records processed in the same run. DATASET_RECORD_FORMAT_ERROR indicates a dataset schema mismatch that will repeat for all records with the same format, so it must be caught and surfaced to the caller rather than retried. try { const result = await client.beta.observability.datasets.records.judge({ datasetRecordId: record.id, judgeId: process.env.MISTRAL_JUDGE_ID, }); return { score: result.answer, analysis: result.analysis }; } catch (error) { if (error instanceof ObservabilityError) { const code = error.detail?.errorCode; if (code === 'JUDGE_NOT_FOUND') { throw new Error(`Judge not found — check judge configuration`); } if (code === 'DATASET_RECORD_NOT_FOUND') { // Record deleted — skip and continue with next record console.warn(`Record not found: ${record.id}`); return null; } if (code === 'DATASET_RECORD_FORMAT_ERROR') { // Schema mismatch — abort batch, surface error to operator throw new Error(`Dataset record format incompatible with judge: ${error.detail?.message}`); } if (code === 'JUDGE_MISTRAL_API_TIMEOUT') { // Retry with backoff or skip this record console.warn(`Judge timed out for record ${record.id}`); return null; } throw new Error(`Observability error: ${error.detail?.message}`); } throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[40][37][38]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.