Skip to content

Document 404 job_not_found and 422 type_mismatch on bulk contacts (Preview) - #610

Merged
VarshSuresh merged 1 commit into
mainfrom
varsh.suresh/document-bulk-job-and-type-mismatch-errors
Jul 29, 2026
Merged

Document 404 job_not_found and 422 type_mismatch on bulk contacts (Preview)#610
VarshSuresh merged 1 commit into
mainfrom
varsh.suresh/document-bulk-job-and-type-mismatch-errors

Conversation

@VarshSuresh

@VarshSuresh VarshSuresh commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Why?

The bulk contacts endpoints can return two error responses this spec did not document, so integrators had no way to know to handle them and would only discover them in production:

  • a 404 / job_not_found when the request body's job.id names a job that does not exist
  • a 422 / type_mismatch when contacts is not an array, or an element of it is not an object

Found while auditing the bulk companies error responses for parity with bulk contacts.

How?

Added the missing 404 response and two extra 422 examples to the three bulk contacts write endpoints, matching the codes and messages the API actually returns. The 404 sits between 401 and 422 to keep responses in numeric order.

Affects the Preview version only, where these endpoints are defined.

Generated with Claude Code


Update: added 403 / forbidden

A third undocumented error response, confirmed against a live response body: appending to a job that has already closed returns 403 with code forbidden and message job <job_id> is closed for new task updates.

Added to the same three write endpoints, ordered before 404. Each now documents 202, 401, 403, 404, 422.

The example uses the job_v2_1 placeholder that the other job examples in this spec already use, rather than a real job id.

@VarshSuresh
VarshSuresh requested a review from a team July 29, 2026 13:31
…view)

The bulk contacts endpoints raise three error responses that were not
documented. Each is reachable through the shared bulk scheduling path but
absent from the spec, so integrators had no way to know to handle them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@VarshSuresh
VarshSuresh force-pushed the varsh.suresh/document-bulk-job-and-type-mismatch-errors branch from 23c85d2 to 4a0d7be Compare July 29, 2026 13:32
@VarshSuresh
VarshSuresh merged commit cd7c0bb into main Jul 29, 2026
3 checks passed
@VarshSuresh
VarshSuresh deleted the varsh.suresh/document-bulk-job-and-type-mismatch-errors branch July 29, 2026 13:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants