Errors
Part of TA-Lib's specification, a reference for AI-agent-driven integration.
What a rejected call reports, in C's spelling. How each code reaches a Rust, Java or C# caller is on the hub; what the library does not detect at all is listed there too.
The caller must
- Branch on the code, never on a message. Java's and C#'s exceptions carry a message for people; its text is not specified. Rust's
Err(RetCode)carries none. - Fix one fault at a time. When a call breaks several conditions, which one it reports is not specified.
- In C, ignore the range after a failure.
*outBegIdxand*outNBElementare unspecified when a call does not returnTA_SUCCESS. A handle out-parameter: ownership. - In C, test internal errors as a range. C returns a value from 5000 to 5999 (rB9), so compare against the range, never
== TA_INTERNAL_ERROR. - Stop after an allocation failure. Nothing after rB8 is defined: not the outputs, not the range, not a stream handle.
Return codes
The codes a batch, lookback or stream call can return:
| Code | TA_RetCode | Returned by |
|---|---|---|
| 0 | TA_SUCCESS | Every call that succeeds, including a batch range that ends before the lookback (count 0, rW2). |
| 2 | TA_BAD_PARAM | A rejected parameter, an absent or too-short buffer, one buffer used twice, a non-finite bar: most batch, opening and advancing conditions; Rust's lookback (rL2); the failed settings calls in C and Rust (rT2). |
| 3 | TA_ALLOC_ERR | A C call that allocates, when the allocation fails (rB8). |
| 12 | TA_OUT_OF_RANGE_START_INDEX | rB1, rS1. |
| 13 | TA_OUT_OF_RANGE_END_INDEX | rB2, rS2, rU4. |
| 17 | TA_INSUFFICIENT_HISTORY | Stream openers only (rS8). A batch call never returns it. |
| 5000 to 5999 | TA_INTERNAL_ERROR + id | rB9. |
The Abstract API returns codes of its own: Abstract API and Metadata. The remaining members of TA_RetCode, declared in ta_defs.h, are returned by nothing.
General rules
rE1 A rejected call reports exactly one code (in Java and C#, one exception) and stops.
rE2 One code across languages. A call that breaks one condition of the batch or stream tables gets that condition's code from every language that can express and detect it.
rE3 A rejected call writes no output buffer. Nothing is promised after rB8 or rB9.
Batch conditions
A batch call accepts 0 <= startIdx <= endIdx <= TA_INDEX_MAX (TA_INDEX_MAX).
| Rule | Condition | Code | Not expressible in |
|---|---|---|---|
| rB1 | startIdx is below 0 or above TA_INDEX_MAX. | TA_OUT_OF_RANGE_START_INDEX | Rust, below 0 (usize) |
| rB2 | endIdx is below 0, above TA_INDEX_MAX, or below startIdx. | TA_OUT_OF_RANGE_END_INDEX | Rust, below 0 |
| rB3 | An optional parameter is outside its accepted values, or the parameters form a combination the function rejects (rP2). | TA_BAD_PARAM | none |
| rB4 | A required argument is absent: an input, an output, or in C a range out-parameter. | TA_BAD_PARAM | none |
| rB5 | A buffer is too short: an input does not reach endIdx (input length), or an output cannot hold the count the call produces (output size). | TA_BAD_PARAM | none; C cannot detect it |
| rB6 | Two outputs are the same buffer. | TA_BAD_PARAM | Rust (safe code) |
| rB7 | An output is omitted that the function does not let a caller decline (rW5). | TA_BAD_PARAM | Rust: cannot decline |
| rB8 | A memory allocation failed. | TA_ALLOC_ERR (C only) | none |
| rB9 | The library found an inconsistency in its own state. | TA_INTERNAL_ERROR + id | none |
rB4. An input or output is absent when it is NULL in C, null or an empty array in Java, an empty slice in Rust, and an empty span in C# (a null array becomes one). An absent one fails whatever the call would produce, even a range that produces no values (rW2). The exception is declining a declinable output with its own spelling (rW5).
rB8. Rust aborts the process, and Java and C# raise their runtime's out-of-memory error.
rB9. A bug in TA-Lib, not in the call: report it, with the number in C. C's TA_SetRetCodeInfo names every value from 5000 to 5999 TA_INTERNAL_ERROR, and a value that is not a TA_RetCode member TA_UNKNOWN_ERR. Rust, Java and C# report TA_INTERNAL_ERROR without an id.
Conditions on other pages
| Call | Rules |
|---|---|
| Lookback, display shift | rL2 fails, rL3 agrees with batch, rL11 fails |
| Stream opening | rS1 empty history, rS2 too long, rS3 parameter, rS4 absent, rS5 length, rS6 one buffer twice, rS7 declined output, rS8 short history |
| Stream advancing | rU1 absent handle, rU2 absent output, rU3 non-finite bar, rU4 index ceiling, rU5 declined output |
| Abstract API | rA1 batch conditions through a holder, rA2 failed bind call, rA3 misuse of a holder, rA4 unknown name |
| Settings | rT2 target, rT3 unstable period, rT4 reading, rT5 range type, rT6 average, rT7 factor, rT8 no change on failure |