jon.recoil.org
forked from
anil.recoil.org/ocaml-jmap
this repo has no description
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** JMAP error types as defined in RFC 8620 Section 3.6.1-3.6.2
7
8 @canonical Jmap.Proto.Error *)
9
10(** {1 Request-Level Errors}
11
12 These errors are returned with an HTTP error status code and a JSON
13 Problem Details body (RFC 7807). *)
14
15(** Request-level error URNs *)
16module Request_error : sig
17 type urn = [
18 | `Unknown_capability
19 (** urn:ietf:params:jmap:error:unknownCapability
20 The client included a capability in "using" that the server does not support. *)
21 | `Not_json
22 (** urn:ietf:params:jmap:error:notJSON
23 The content type was not application/json or the request was not valid JSON. *)
24 | `Not_request
25 (** urn:ietf:params:jmap:error:notRequest
26 The request was valid JSON but not a valid JMAP Request object. *)
27 | `Limit
28 (** urn:ietf:params:jmap:error:limit
29 A server-defined limit was reached. *)
30 | `Other of string
31 (** Other URN not in the standard set. *)
32 ]
33
34 val urn_to_string : urn -> string
35 (** [urn_to_string urn] returns the URN string. *)
36
37 val urn_of_string : string -> urn
38 (** [urn_of_string s] parses a URN string. *)
39
40 type t = {
41 type_ : urn;
42 (** The error type URN. *)
43 status : int;
44 (** HTTP status code. *)
45 title : string option;
46 (** Short human-readable summary. *)
47 detail : string option;
48 (** Longer human-readable explanation. *)
49 limit : string option;
50 (** For "limit" errors, the name of the limit that was exceeded. *)
51 }
52 (** A request-level error per RFC 7807 Problem Details. *)
53
54 val jsont : t Jsont.t
55 (** JSON codec for request-level errors. *)
56end
57
58(** {1 Method-Level Errors}
59
60 These are returned as the second element of an Invocation tuple
61 when a method call fails. *)
62
63(** Standard method error types per RFC 8620 Section 3.6.2 *)
64type method_error_type = [
65 | `Server_unavailable
66 (** The server is temporarily unavailable. *)
67 | `Server_fail
68 (** An unexpected error occurred. *)
69 | `Server_partial_fail
70 (** Some, but not all, changes were successfully made. *)
71 | `Unknown_method
72 (** The method name is not recognized. *)
73 | `Invalid_arguments
74 (** One or more arguments are invalid. *)
75 | `Invalid_result_reference
76 (** A result reference could not be resolved. *)
77 | `Forbidden
78 (** The method/arguments are valid but forbidden. *)
79 | `Account_not_found
80 (** The accountId does not correspond to a valid account. *)
81 | `Account_not_supported_by_method
82 (** The account does not support this method. *)
83 | `Account_read_only
84 (** The account is read-only. *)
85 | `Other of string
86 (** Other error type not in the standard set. *)
87]
88
89val method_error_type_to_string : method_error_type -> string
90(** [method_error_type_to_string t] returns the type string. *)
91
92val method_error_type_of_string : string -> method_error_type
93(** [method_error_type_of_string s] parses a type string. *)
94
95(** A method-level error response. *)
96type method_error = {
97 type_ : method_error_type;
98 (** The error type. *)
99 description : string option;
100 (** Human-readable description of the error. *)
101}
102
103val method_error_jsont : method_error Jsont.t
104(** JSON codec for method errors. *)
105
106(** {1 SetError}
107
108 Errors returned in notCreated/notUpdated/notDestroyed responses. *)
109
110(** Standard SetError types per RFC 8620 Section 5.3 and RFC 8621 Section 7 *)
111type set_error_type = [
112 | `Forbidden
113 (** The operation is not permitted. *)
114 | `Over_quota
115 (** The maximum server quota has been reached. *)
116 | `Too_large
117 (** The object is too large. *)
118 | `Rate_limit
119 (** Too many objects of this type have been created recently. *)
120 | `Not_found
121 (** The id does not exist (for update/destroy). *)
122 | `Invalid_patch
123 (** The PatchObject is invalid. *)
124 | `Will_destroy
125 (** The object will be destroyed by another operation in the request. *)
126 | `Invalid_properties
127 (** Some properties were invalid. *)
128 | `Singleton
129 (** Only one object of this type can exist (for create). *)
130 | `Forbidden_mail_from
131 (** RFC 8621: The server does not permit the user to send from the address. *)
132 | `Forbidden_from
133 (** RFC 8621: The server does not permit the user to send a message with
134 the From header of the message to be sent. *)
135 | `Forbidden_to_send
136 (** RFC 8621: The user does not have permission to send at all. *)
137 | `Other of string
138 (** Other error type. *)
139]
140
141val set_error_type_to_string : set_error_type -> string
142val set_error_type_of_string : string -> set_error_type
143
144(** A SetError object. *)
145type set_error = {
146 type_ : set_error_type;
147 (** The error type. *)
148 description : string option;
149 (** Human-readable description. *)
150 properties : string list option;
151 (** For invalidProperties errors, the list of invalid property names. *)
152}
153
154val set_error : ?description:string -> ?properties:string list -> set_error_type -> set_error
155(** [set_error ?description ?properties type_] creates a SetError. *)
156
157val set_error_jsont : set_error Jsont.t
158(** JSON codec for SetError. *)